@xevy/cli 0.1.14 → 0.1.16

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
@@ -149,35 +149,34 @@ xevy dev cb49c02e-66d8-4475-95a8-6f3930643ec8
149
149
  xevy dev VI22-07 --base https://xevy.example.com
150
150
  ```
151
151
 
152
+ The command stays attached across normal Pi exits and transient terminal
153
+ disconnects. It shows startup/restart status while the remote terminal is being
154
+ prepared; press `Ctrl+]` to detach intentionally and leave the Dev Session
155
+ running.
156
+
152
157
  The CLI resolves an exact task ID or task code, attaches to its existing Dev
153
- Session, or starts one from a linked repository. When several accessible tasks
154
- share a code, or a project has several linked repositories, it presents
155
- a numbered selector. It restores the recent conversation for the session branch
156
- and attaches to an already-running agent turn instead of submitting a duplicate.
157
- Use it like a normal coding-agent conversation: ask questions, inspect the
158
- workspace, or request changes. Conversational and read-only turns do not create
159
- empty commits. When a turn changes code, the server commits any remaining edits
160
- and pushes the resumable Dev Session branch automatically.
161
-
162
- `xevy dev` is a remote client. It does **not** install or run local Pi, clone the
163
- repository, open a shell or PTY, use SSH, or invoke Docker. Ctrl+C, terminal EOF,
164
- and `/detach` only disconnect the local client; the server session and its pushed
165
- branch remain available for safe resume.
166
-
167
- Available commands while attached:
158
+ Session, or starts one from a linked repository. It then renders Pi's native TUI
159
+ from the isolated remote workspace: normal composer, thinking, tools, history,
160
+ keyboard shortcuts, and session resume all behave like Pi on a local machine.
161
+ When several accessible tasks share a code, or a project has several linked
162
+ repositories, the CLI presents a numbered selector first.
163
+
164
+ `xevy dev` is only a terminal transport. Pi, Git credentials, the repository,
165
+ and Docker remain on the server. Press `Ctrl+]` to detach without stopping Pi;
166
+ run the same command again to reattach. Pi conversation history is stored in the
167
+ bounded Dev Session volume. The controller periodically commits work and pushes
168
+ the resumable Dev Session branch; exiting Pi also commits and pushes any final
169
+ edits. You do not need to ask the agent to commit after every prompt.
170
+
171
+ Terminal control:
168
172
 
169
173
  ```text
170
- /status Refresh the lifecycle status and URL
171
- /logs Show the latest session logs
172
- /open Request a fresh one-use browser link and open it when supported
173
- /finish Merge into the task branch and stop
174
- /stop Stop without merging (the pushed session branch remains preserved)
175
- /detach Disconnect this terminal without stopping anything
176
- /help Show the command list
174
+ Ctrl+] Disconnect this terminal without stopping Pi or the Dev Session
177
175
  ```
178
176
 
179
- `/finish` and `/stop` always ask for confirmation. A heartbeat keeps the session
180
- active while the CLI is attached, within the server's hard expiry limit.
177
+ Use the task's Dev Session panel in Xevy to open the live site, stop the session,
178
+ or finish and redeploy after exiting Pi. A heartbeat keeps the session active
179
+ while the CLI is attached, within the server's hard expiry limit.
181
180
 
182
181
  Host precedence is `--base`, `XEVY_BASE`, the saved credentials `baseUrl`, then
183
182
  `https://xevy.ai`. API-key precedence is `XEVY_API_KEY`, then the saved key in
@@ -1,5 +1,6 @@
1
1
  import { spawn } from "node:child_process";
2
2
  import readline from "node:readline";
3
+ import WebSocket from "ws";
3
4
 
4
5
  const DEFAULT_BASE = "https://xevy.ai";
5
6
  const TERMINAL_EXECUTION_STATUSES = new Set(["succeeded", "failed", "cancelled"]);
@@ -12,6 +13,10 @@ const HEARTBEAT_INTERVAL_MS = 60_000;
12
13
  const SESSION_POLL_INTERVAL_MS = 2_000;
13
14
  const SESSION_START_TIMEOUT_MS = 10 * 60_000;
14
15
  const EXECUTION_RECONNECT_LIMIT = 8;
16
+ const TERMINAL_RECONNECT_LIMIT = 8;
17
+ const TERMINAL_RECONNECT_MAX_DELAY_MS = 5_000;
18
+ const TERMINAL_STABLE_RUNTIME_MS = 10_000;
19
+ const TERMINAL_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
15
20
 
16
21
  export function parseCredentialsText(source) {
17
22
  const values = {};
@@ -537,6 +542,64 @@ async function waitForReady({ api, sessionPath, initialSession, writeLine, sleep
537
542
  return session;
538
543
  }
539
544
 
545
+ /** A deliberately restrained terminal status indicator. It animates only on
546
+ * the real interactive stdout; redirected output, CI, and tests receive stable
547
+ * newline-delimited status messages. */
548
+ export function createTerminalStatus({ output, writeLine, animate }) {
549
+ const shouldAnimate = animate ?? Boolean(
550
+ output === process.stdout
551
+ && output.isTTY
552
+ && !process.env.CI
553
+ && process.env.TERM !== "dumb",
554
+ );
555
+ let label = "";
556
+ let previousStaticLabel = "";
557
+ let frame = 0;
558
+ let timer = null;
559
+ let painted = false;
560
+
561
+ const render = () => {
562
+ if (!label) return;
563
+ painted = true;
564
+ output.write(`\r\x1b[2K${TERMINAL_SPINNER_FRAMES[frame % TERMINAL_SPINNER_FRAMES.length]} ${label}`);
565
+ frame += 1;
566
+ };
567
+ const clear = () => {
568
+ if (timer) clearInterval(timer);
569
+ timer = null;
570
+ if (painted) output.write("\r\x1b[2K");
571
+ painted = false;
572
+ };
573
+
574
+ return {
575
+ update(nextLabel) {
576
+ label = String(nextLabel || "");
577
+ if (!label) return;
578
+ if (!shouldAnimate) {
579
+ if (label !== previousStaticLabel) writeLine(label);
580
+ previousStaticLabel = label;
581
+ return;
582
+ }
583
+ if (!timer) {
584
+ render();
585
+ timer = setInterval(render, 80);
586
+ timer.unref?.();
587
+ }
588
+ },
589
+ succeed(finalLabel) {
590
+ clear();
591
+ label = "";
592
+ previousStaticLabel = "";
593
+ if (finalLabel) writeLine(`✓ ${finalLabel}`);
594
+ },
595
+ stop() {
596
+ clear();
597
+ label = "";
598
+ previousStaticLabel = "";
599
+ },
600
+ };
601
+ }
602
+
540
603
  function sessionSummary(task, session, writeLine) {
541
604
  const url = canonicalSessionUrl(session.hostname);
542
605
  writeLine("\nDev Session");
@@ -545,7 +608,190 @@ function sessionSummary(task, session, writeLine) {
545
608
  writeLine(` Branch ${session.config?.branch || "unknown"}`);
546
609
  writeLine(` Status ${session.status}`);
547
610
  writeLine(` Expires ${session.expiresAt || "server-managed"}`);
548
- writeLine("\n/open · /status · /logs · /finish · /stop · /detach · /help\n");
611
+ writeLine("\nNative Pi terminal · press Ctrl+] to detach and leave it running\n");
612
+ }
613
+
614
+ async function attachNativeTerminal({
615
+ api,
616
+ base,
617
+ sessionPath,
618
+ input,
619
+ output,
620
+ signal,
621
+ onReady,
622
+ WebSocketImpl = WebSocket,
623
+ }) {
624
+ const ticket = await api.request(`${sessionPath}/terminal-ticket`, { method: "POST", body: {}, signal });
625
+ if (!ticket?.ticket || !ticket?.terminalPath) throw new Error("Xevy did not return a terminal ticket.");
626
+ const url = new URL(ticket.terminalPath, `${base}/`);
627
+ url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
628
+
629
+ return new Promise((resolve, reject) => {
630
+ const socket = new WebSocketImpl(url, {
631
+ headers: { "X-Xevy-Terminal-Ticket": ticket.ticket },
632
+ maxPayload: 2 * 1024 * 1024,
633
+ });
634
+ let ready = false;
635
+ let settled = false;
636
+ let rawEnabled = false;
637
+ let detachedByUser = false;
638
+ const connectedAt = Date.now();
639
+ const pendingOutput = [];
640
+ const onAbort = () => {
641
+ detachedByUser = true;
642
+ if (socket.readyState === WebSocketImpl.OPEN) socket.close(1000, "client_detach");
643
+ else socket.terminate?.();
644
+ finish(null, { reason: "detached", code: 1000, durationMs: Date.now() - connectedAt });
645
+ };
646
+ const finish = (error, result) => {
647
+ if (settled) return;
648
+ settled = true;
649
+ input.off("data", onInput);
650
+ process.off("SIGWINCH", onResize);
651
+ signal?.removeEventListener("abort", onAbort);
652
+ if (rawEnabled && typeof input.setRawMode === "function") input.setRawMode(false);
653
+ if (error) reject(error);
654
+ else resolve(result);
655
+ };
656
+ const sendResize = () => {
657
+ if (socket.readyState !== WebSocketImpl.OPEN) return;
658
+ socket.send(JSON.stringify({
659
+ type: "resize",
660
+ cols: Number(output.columns) || 80,
661
+ rows: Number(output.rows) || 24,
662
+ }));
663
+ };
664
+ const onResize = () => sendResize();
665
+ const onInput = (chunk) => {
666
+ const value = Buffer.from(chunk);
667
+ const detachAt = value.indexOf(0x1d);
668
+ if (detachAt >= 0) {
669
+ detachedByUser = true;
670
+ if (detachAt > 0 && socket.readyState === WebSocketImpl.OPEN) {
671
+ socket.send(value.subarray(0, detachAt), { binary: true });
672
+ }
673
+ output.write("\r\nDetached. Pi and the Dev Session are still running.\r\n");
674
+ socket.close(1000, "client_detach");
675
+ finish(null, { reason: "detached", code: 1000, durationMs: Date.now() - connectedAt });
676
+ return;
677
+ }
678
+ if (socket.readyState === WebSocketImpl.OPEN) socket.send(value, { binary: true });
679
+ };
680
+
681
+ if (signal?.aborted) {
682
+ onAbort();
683
+ return;
684
+ }
685
+ signal?.addEventListener("abort", onAbort, { once: true });
686
+
687
+ socket.on("message", (data, isBinary) => {
688
+ if (isBinary) {
689
+ const chunk = Buffer.from(data);
690
+ if (ready) output.write(chunk);
691
+ else pendingOutput.push(chunk);
692
+ return;
693
+ }
694
+ let control;
695
+ try { control = JSON.parse(data.toString()); } catch { return; }
696
+ if (control.type === "ready" && !ready) {
697
+ ready = true;
698
+ onReady?.();
699
+ for (const chunk of pendingOutput.splice(0)) output.write(chunk);
700
+ if (typeof input.setRawMode === "function") {
701
+ input.setRawMode(true);
702
+ rawEnabled = true;
703
+ }
704
+ input.resume?.();
705
+ input.on("data", onInput);
706
+ process.on("SIGWINCH", onResize);
707
+ sendResize();
708
+ } else if (control.type === "error") {
709
+ finish(new Error(control.message || "Dev Session terminal failed."));
710
+ }
711
+ });
712
+ socket.once("unexpected-response", (_request, response) => {
713
+ finish(new Error(`Dev Session terminal refused the connection (HTTP ${response.statusCode || 500}).`));
714
+ });
715
+ socket.once("error", (error) => finish(new Error(`Dev Session terminal connection failed: ${error.message}`)));
716
+ socket.once("close", (code) => {
717
+ if (!ready && !settled) finish(new Error(`Dev Session terminal closed before it was ready (code ${code}).`));
718
+ else if (!settled) finish(null, {
719
+ reason: detachedByUser ? "detached" : code === 1000 ? "terminal-exit" : "transport-lost",
720
+ code,
721
+ durationMs: Date.now() - connectedAt,
722
+ });
723
+ });
724
+ });
725
+ }
726
+
727
+ async function attachNativeTerminalPersistently({
728
+ api,
729
+ base,
730
+ sessionPath,
731
+ input,
732
+ output,
733
+ signal,
734
+ sleep,
735
+ writeLine,
736
+ WebSocketImpl,
737
+ animateStatus,
738
+ }) {
739
+ const status = createTerminalStatus({ output, writeLine, animate: animateStatus });
740
+ let reconnecting = false;
741
+ let consecutiveFailures = 0;
742
+ try {
743
+ while (!signal?.aborted) {
744
+ status.update(reconnecting ? "Restarting remote Pi terminal…" : "Starting remote Pi terminal…");
745
+ try {
746
+ const result = await attachNativeTerminal({
747
+ api,
748
+ base,
749
+ sessionPath,
750
+ input,
751
+ output,
752
+ signal,
753
+ onReady: () => status.succeed(reconnecting ? "Pi terminal restarted" : "Pi terminal ready"),
754
+ WebSocketImpl,
755
+ });
756
+ if (result?.reason === "detached") return;
757
+ reconnecting = true;
758
+ consecutiveFailures = result?.durationMs >= TERMINAL_STABLE_RUNTIME_MS
759
+ ? 0
760
+ : consecutiveFailures + 1;
761
+ status.update(result?.reason === "transport-lost"
762
+ ? "Terminal connection lost · reconnecting…"
763
+ : "Pi exited · restarting terminal…");
764
+ } catch (error) {
765
+ if (signal?.aborted) throw error;
766
+ if (error instanceof DevSessionApiError && ![409, 502, 503, 504].includes(error.status)) throw error;
767
+ reconnecting = true;
768
+ consecutiveFailures += 1;
769
+ status.update("Terminal is not ready yet · retrying…");
770
+ }
771
+
772
+ if (consecutiveFailures >= TERMINAL_RECONNECT_LIMIT) {
773
+ throw new Error("The remote Pi terminal repeatedly exited before stabilizing. The Dev Session remains active; check its logs and rerun `xevy dev` after correcting the startup error.");
774
+ }
775
+ await sleep(
776
+ Math.min(500 * 2 ** Math.max(0, consecutiveFailures - 1), TERMINAL_RECONNECT_MAX_DELAY_MS),
777
+ signal,
778
+ );
779
+ let current = null;
780
+ try {
781
+ current = await api.request(`${sessionPath}/`, { signal });
782
+ } catch (error) {
783
+ if (signal?.aborted) throw error;
784
+ if (error instanceof DevSessionApiError && [401, 403, 404].includes(error.status)) throw error;
785
+ status.update("Session status unavailable · retrying terminal…");
786
+ }
787
+ if (current && !current.session) throw new Error("The Dev Session disappeared while reconnecting the terminal.");
788
+ if (current?.session && SESSION_TERMINAL_STATUSES.has(current.session.status)) {
789
+ throw new Error(current.session.error || `Dev Session ${current.session.status}.`);
790
+ }
791
+ }
792
+ } finally {
793
+ status.stop();
794
+ }
549
795
  }
550
796
 
551
797
  function commandHelp(writeLine) {
@@ -747,6 +993,25 @@ export async function runDevSession(options) {
747
993
  });
748
994
  sessionSummary(task, session, writeLine);
749
995
 
996
+ const nativeTerminal = options.nativeTerminal
997
+ ?? (input === process.stdin && output === process.stdout);
998
+ if (interactive && nativeTerminal) {
999
+ await attachNativeTerminalPersistently({
1000
+ api,
1001
+ base,
1002
+ sessionPath,
1003
+ input,
1004
+ output,
1005
+ signal: detachController.signal,
1006
+ sleep,
1007
+ writeLine,
1008
+ WebSocketImpl: options.webSocketImpl || WebSocket,
1009
+ animateStatus: options.animateStatus,
1010
+ });
1011
+ detached = true;
1012
+ return { task, session, detached: true };
1013
+ }
1014
+
750
1015
  const renderState = {
751
1016
  messageIds: new Set(),
752
1017
  lastExecutionStatus: null,
package/bin/xevy.mjs CHANGED
@@ -133,11 +133,11 @@ function devUsage() {
133
133
  xevy dev <task-id-or-code> [--base <url>]
134
134
 
135
135
  Connects this terminal to the task's remote Dev Session. The command attaches
136
- to an existing session or starts one from a linked repository. It
137
- does not run a local coding agent, shell, Docker container, or repository clone.
136
+ to an existing session or starts one from a linked repository, then opens Pi's
137
+ native interactive terminal inside the isolated remote workspace.
138
138
 
139
- Inside the session:
140
- /status /logs /open /finish /stop /detach /help
139
+ Terminal control:
140
+ Ctrl+] Detach without stopping Pi or the Dev Session
141
141
 
142
142
  Credentials:
143
143
  XEVY_API_KEY takes precedence over ~/.config/xevy/credentials.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xevy/cli",
3
- "version": "0.1.14",
3
+ "version": "0.1.16",
4
4
  "description": "Xevy CLI — connect to remote Dev Sessions, configure credentials, pi, coding-agent skills, and MCP, and keep integrations current.",
5
5
  "type": "module",
6
6
  "keywords": [
@@ -23,6 +23,9 @@
23
23
  "engines": {
24
24
  "node": ">=18"
25
25
  },
26
+ "dependencies": {
27
+ "ws": "^8.18.3"
28
+ },
26
29
  "publishConfig": {
27
30
  "access": "public"
28
31
  }