@xevy/cli 0.1.18 → 0.1.21

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
@@ -57,7 +57,8 @@ OAuth.
57
57
  ```bash
58
58
  xevy # open an interactive pi session with Xevy loaded
59
59
  xevy "summarise this repo" # or send a one-off prompt
60
- xevy dev VI22-07 # attach to a task's remote Dev Session
60
+ xevy dev task/VI22-07 # attach to a task's remote Dev Session
61
+ xevy dev xevy/xevyai # start or resume your personal project session
61
62
  ```
62
63
 
63
64
  That's it — you're set up. The sections below are reference for when you need more detail.
@@ -140,13 +141,13 @@ xevy "summarise this repo" # forwards the prompt to pi
140
141
 
141
142
  ## `xevy dev`
142
143
 
143
- Connect an interactive terminal to the coding agent attached to a task's remote
144
- Dev Session:
144
+ Connect an interactive terminal to a task or personal remote Dev Session:
145
145
 
146
146
  ```bash
147
- xevy dev VI22-07
148
- xevy dev cb49c02e-66d8-4475-95a8-6f3930643ec8
149
- xevy dev VI22-07 --base https://xevy.example.com
147
+ xevy dev task/VI22-07
148
+ xevy dev task/cb49c02e-66d8-4475-95a8-6f3930643ec8
149
+ xevy dev xevy/xevyai
150
+ xevy dev xevy/xevyai --base https://xevy.example.com
150
151
  ```
151
152
 
152
153
  The command stays attached across normal Pi exits and transient terminal
@@ -154,12 +155,13 @@ disconnects. After Pi exits, it waits three seconds before restarting and shows
154
155
  a `Ctrl+C` detach hint; press `Ctrl+]` while attached to leave the Dev Session
155
156
  running immediately.
156
157
 
157
- The CLI resolves an exact task ID or task code, attaches to its existing Dev
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.
158
+ The CLI grammar is explicit: `task/<task-id-or-code>` selects a task session,
159
+ while `<workspace>/<project>` selects your default personal project session.
160
+ Bare task IDs, aliases, and scope-guessing are intentionally unsupported. After
161
+ the target is resolved, the CLI renders Pi's native TUI from the isolated remote
162
+ workspace: normal composer, thinking, tools, history, keyboard shortcuts, and
163
+ session resume all behave like Pi on a local machine. A multi-repository project
164
+ asks for its runtime repository only on first start.
163
165
 
164
166
  `xevy dev` is only a terminal transport. Pi, Git credentials, the repository,
165
167
  and Docker remain on the server. Press `Ctrl+]` to detach without stopping Pi;
@@ -13,11 +13,30 @@ const HEARTBEAT_INTERVAL_MS = 60_000;
13
13
  const SESSION_POLL_INTERVAL_MS = 2_000;
14
14
  const SESSION_START_TIMEOUT_MS = 10 * 60_000;
15
15
  const EXECUTION_RECONNECT_LIMIT = 8;
16
- const TERMINAL_RECONNECT_LIMIT = 8;
17
- const TERMINAL_RECONNECT_MAX_DELAY_MS = 5_000;
18
- const TERMINAL_RESTART_GRACE_MS = 3_000;
19
- const TERMINAL_STABLE_RUNTIME_MS = 10_000;
16
+ const TERMINAL_START_ATTEMPT_LIMIT = 8;
17
+ const TERMINAL_START_MAX_DELAY_MS = 5_000;
20
18
  const TERMINAL_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
19
+ const DEV_TARGET_SEGMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
20
+
21
+ function parseDevTarget(value) {
22
+ const reference = String(value || "").trim();
23
+ const segments = reference.split("/");
24
+ const usage = "Use `task/<task-id-or-code>` or `<workspace>/<project>`.";
25
+ if (segments.length !== 2 || segments.some((segment) => !segment)) {
26
+ throw new Error(`Invalid Dev Session target '${reference}'. ${usage}`);
27
+ }
28
+ if (segments.some((segment) => !DEV_TARGET_SEGMENT_PATTERN.test(segment))) {
29
+ throw new Error(`Invalid Dev Session target '${reference}'. Identifiers may use letters, numbers, '.', '_', and '-'.`);
30
+ }
31
+ if (segments[0] === "task") {
32
+ return { kind: "task", taskReference: segments[1] };
33
+ }
34
+ return {
35
+ kind: "personal",
36
+ workspaceIdentifier: segments[0],
37
+ projectIdentifier: segments[1],
38
+ };
39
+ }
21
40
 
22
41
  export function parseCredentialsText(source) {
23
42
  const values = {};
@@ -55,11 +74,11 @@ export function normalizeBaseUrl(value) {
55
74
 
56
75
  export function parseDevCommandArgs(argv) {
57
76
  const args = [...argv];
58
- let taskReference = "";
77
+ let targetReference = "";
59
78
  let base = null;
60
79
  while (args.length > 0) {
61
80
  const argument = args.shift();
62
- if (argument === "-h" || argument === "--help") return { help: true, taskReference: "", base: null };
81
+ if (argument === "-h" || argument === "--help") return { help: true, target: null, base: null };
63
82
  if (argument === "--base") {
64
83
  const value = args.shift();
65
84
  if (!value) throw new Error("Missing value for --base");
@@ -67,11 +86,13 @@ export function parseDevCommandArgs(argv) {
67
86
  continue;
68
87
  }
69
88
  if (argument.startsWith("-")) throw new Error(`Unknown option for \`xevy dev\`: ${argument}.`);
70
- if (taskReference) throw new Error("`xevy dev` accepts one task ID or task code.");
71
- taskReference = argument;
89
+ if (targetReference) throw new Error("`xevy dev` accepts one Dev Session target.");
90
+ targetReference = argument;
91
+ }
92
+ if (!targetReference) {
93
+ throw new Error("Usage: xevy dev <task/<task-id-or-code>|workspace/project> [--base <url>]");
72
94
  }
73
- if (!taskReference) throw new Error("Usage: xevy dev <task-id-or-code> [--base <url>]");
74
- return { help: false, taskReference, base };
95
+ return { help: false, target: parseDevTarget(targetReference), base };
75
96
  }
76
97
 
77
98
  export function resolveDevConnection({
@@ -600,12 +621,17 @@ export function createTerminalStatus({ output, writeLine, animate }) {
600
621
  };
601
622
  }
602
623
 
603
- function sessionSummary(task, session, base, writeLine) {
604
- const url = devSessionLaunchUrl(base, task);
624
+ function sessionSummary(context, session, base, writeLine) {
625
+ const task = context.kind === "task" ? context.task : null;
626
+ const url = task
627
+ ? devSessionLaunchUrl(base, task)
628
+ : new URL(`/agent?session=${encodeURIComponent(session.id)}`, `${normalizeBaseUrl(base)}/`).toString();
605
629
  writeLine("\nDev Session");
606
- writeLine(` Task ${formatTask(task)}`);
607
- writeLine(` Site ${url || "not available yet"}`);
608
- writeLine(` Branch ${session.config?.branch || "unknown"}`);
630
+ if (task) writeLine(` Task ${formatTask(task)}`);
631
+ else writeLine(` Project ${context.workspace.identifier}/${context.project.identifier} · Personal`);
632
+ writeLine(` Workbench ${url || "not available yet"}`);
633
+ writeLine(` Preview ${session.config?.runtimeMode === "none" || !session.hostname ? "none (workspace only)" : `https://${session.hostname}`}`);
634
+ writeLine(` Branch ${session.branch || session.config?.branch || "unknown"}`);
609
635
  writeLine(` Status ${session.status}`);
610
636
  writeLine(` Expires ${session.expiresAt || "server-managed"}`);
611
637
  writeLine("\nNative Pi terminal · press Ctrl+] to detach and leave it running\n");
@@ -619,6 +645,7 @@ async function attachNativeTerminal({
619
645
  output,
620
646
  signal,
621
647
  onReady,
648
+ reattachHint,
622
649
  WebSocketImpl = WebSocket,
623
650
  }) {
624
651
  const ticket = await api.request(`${sessionPath}/terminal-ticket`, { method: "POST", body: {}, signal });
@@ -634,6 +661,7 @@ async function attachNativeTerminal({
634
661
  let ready = false;
635
662
  let settled = false;
636
663
  let rawEnabled = false;
664
+ let resumedInput = false;
637
665
  let detachedByUser = false;
638
666
  const connectedAt = Date.now();
639
667
  const pendingOutput = [];
@@ -650,6 +678,13 @@ async function attachNativeTerminal({
650
678
  process.off("SIGWINCH", onResize);
651
679
  signal?.removeEventListener("abort", onAbort);
652
680
  if (rawEnabled && typeof input.setRawMode === "function") input.setRawMode(false);
681
+ // A resumed stdin keeps its libuv handle referenced, so without this the
682
+ // process sits there after detaching and never gives the shell back.
683
+ if (resumedInput) {
684
+ input.pause?.();
685
+ input.unref?.();
686
+ resumedInput = false;
687
+ }
653
688
  if (error) reject(error);
654
689
  else resolve(result);
655
690
  };
@@ -671,6 +706,7 @@ async function attachNativeTerminal({
671
706
  socket.send(value.subarray(0, detachAt), { binary: true });
672
707
  }
673
708
  output.write("\r\nDetached. Pi and the Dev Session are still running.\r\n");
709
+ if (reattachHint) output.write(`${reattachHint}\r\n`);
674
710
  socket.close(1000, "client_detach");
675
711
  finish(null, { reason: "detached", code: 1000, durationMs: Date.now() - connectedAt });
676
712
  return;
@@ -702,6 +738,7 @@ async function attachNativeTerminal({
702
738
  rawEnabled = true;
703
739
  }
704
740
  input.resume?.();
741
+ resumedInput = true;
705
742
  input.on("data", onInput);
706
743
  process.on("SIGWINCH", onResize);
707
744
  sendResize();
@@ -724,10 +761,18 @@ async function attachNativeTerminal({
724
761
  });
725
762
  }
726
763
 
727
- async function attachNativeTerminalPersistently({
764
+ /**
765
+ * Attaches once and returns when the attachment ends — by Ctrl+], because Pi
766
+ * exited, or because the connection dropped. It does NOT reconnect: silently
767
+ * restarting the remote terminal fought whoever was trying to leave and hid
768
+ * why Pi stopped. Retries before the first attach are a different thing and
769
+ * stay, since a session that is still provisioning has nothing to attach to.
770
+ */
771
+ async function attachNativeTerminalOnce({
728
772
  api,
729
773
  base,
730
774
  sessionPath,
775
+ reattachHint,
731
776
  input,
732
777
  output,
733
778
  signal,
@@ -737,12 +782,10 @@ async function attachNativeTerminalPersistently({
737
782
  animateStatus,
738
783
  }) {
739
784
  const status = createTerminalStatus({ output, writeLine, animate: animateStatus });
740
- let reconnecting = false;
741
- let consecutiveFailures = 0;
785
+ let attempts = 0;
742
786
  try {
743
787
  while (!signal?.aborted) {
744
- let reconnectDelayMs = null;
745
- status.update(reconnecting ? "Restarting remote Pi terminal…" : "Starting remote Pi terminal…");
788
+ status.update(attempts === 0 ? "Starting remote Pi terminal…" : "Terminal is not ready yet · retrying…");
746
789
  try {
747
790
  const result = await attachNativeTerminal({
748
791
  api,
@@ -751,47 +794,36 @@ async function attachNativeTerminalPersistently({
751
794
  input,
752
795
  output,
753
796
  signal,
754
- onReady: () => status.succeed(reconnecting ? "Pi terminal restarted" : "Pi terminal ready"),
797
+ reattachHint,
798
+ onReady: () => status.succeed("Pi terminal ready"),
755
799
  WebSocketImpl,
756
800
  });
757
801
  if (result?.reason === "detached") return;
758
- reconnecting = true;
759
- consecutiveFailures = result?.durationMs >= TERMINAL_STABLE_RUNTIME_MS
760
- ? 0
761
- : consecutiveFailures + 1;
762
- if (result?.reason === "transport-lost") {
763
- status.update("Terminal connection lost · reconnecting…");
764
- } else {
765
- reconnectDelayMs = TERMINAL_RESTART_GRACE_MS;
766
- status.update("Pi exited · restarting in 3 seconds · Ctrl+C to detach");
767
- }
802
+ status.stop();
803
+ // The attachment ended on its own; say why and leave the session up.
804
+ writeLine(result?.reason === "transport-lost"
805
+ ? "\nConnection to the Dev Session terminal was lost. The Dev Session is still running."
806
+ : "\nPi exited. The Dev Session is still running.");
807
+ if (reattachHint) writeLine(reattachHint);
808
+ return;
768
809
  } catch (error) {
769
810
  if (signal?.aborted) throw error;
770
811
  if (error instanceof DevSessionApiError && ![409, 502, 503, 504].includes(error.status)) throw error;
771
- reconnecting = true;
772
- consecutiveFailures += 1;
812
+ attempts += 1;
813
+ if (attempts >= TERMINAL_START_ATTEMPT_LIMIT) {
814
+ throw new Error("The remote Pi terminal never became ready. The Dev Session remains active; check its logs and rerun `xevy dev` after correcting the startup error.");
815
+ }
773
816
  status.update("Terminal is not ready yet · retrying…");
774
- }
775
-
776
- if (consecutiveFailures >= TERMINAL_RECONNECT_LIMIT) {
777
- 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.");
778
- }
779
- await sleep(
780
- reconnectDelayMs
781
- ?? Math.min(500 * 2 ** Math.max(0, consecutiveFailures - 1), TERMINAL_RECONNECT_MAX_DELAY_MS),
782
- signal,
783
- );
784
- let current = null;
785
- try {
786
- current = await api.request(`${sessionPath}/`, { signal });
787
- } catch (error) {
788
- if (signal?.aborted) throw error;
789
- if (error instanceof DevSessionApiError && [401, 403, 404].includes(error.status)) throw error;
790
- status.update("Session status unavailable · retrying terminal…");
791
- }
792
- if (current && !current.session) throw new Error("The Dev Session disappeared while reconnecting the terminal.");
793
- if (current?.session && SESSION_TERMINAL_STATUSES.has(current.session.status)) {
794
- throw new Error(current.session.error || `Dev Session ${current.session.status}.`);
817
+ await sleep(Math.min(500 * 2 ** (attempts - 1), TERMINAL_START_MAX_DELAY_MS), signal);
818
+ const current = await api.request(`${sessionPath}/`, { signal }).catch((cause) => {
819
+ if (signal?.aborted || (cause instanceof DevSessionApiError && [401, 403, 404].includes(cause.status))) throw cause;
820
+ status.update("Session status unavailable · retrying terminal…");
821
+ return null;
822
+ });
823
+ if (current && !current.session) throw new Error("The Dev Session disappeared while starting the terminal.");
824
+ if (current?.session && SESSION_TERMINAL_STATUSES.has(current.session.status)) {
825
+ throw new Error(current.session.error || `Dev Session ${current.session.status}.`);
826
+ }
795
827
  }
796
828
  }
797
829
  } finally {
@@ -799,11 +831,11 @@ async function attachNativeTerminalPersistently({
799
831
  }
800
832
  }
801
833
 
802
- function commandHelp(writeLine) {
834
+ function commandHelp(writeLine, hasWebPreview = true) {
803
835
  writeLine("Commands:");
804
836
  writeLine(" /status Refresh session status");
805
837
  writeLine(" /logs Show the latest Dev Session logs");
806
- writeLine(" /open Open a fresh one-use Dev Session URL");
838
+ if (hasWebPreview) writeLine(" /open Open a fresh one-use Dev Session URL");
807
839
  writeLine(" /finish Save the task branch and stop");
808
840
  writeLine(" /stop Stop the Dev Session without finishing");
809
841
  writeLine(" /detach Leave it running and exit this CLI");
@@ -849,8 +881,10 @@ export async function runDevSession(options) {
849
881
  if (!token.startsWith("xevy_pk_")) {
850
882
  throw new Error("A Xevy API key is required. Run `xevy setup --credentials` first.");
851
883
  }
852
- const taskReference = String(options.taskReference || "").trim();
853
- if (!taskReference) throw new Error("Usage: xevy dev <task-id-or-code> [--base <url>]");
884
+ const target = options.target;
885
+ if (!target || !["task", "personal"].includes(target.kind)) {
886
+ throw new Error("Usage: xevy dev <task/<task-id-or-code>|workspace/project> [--base <url>]");
887
+ }
854
888
 
855
889
  const fetchImpl = options.fetchImpl || globalThis.fetch;
856
890
  if (typeof fetchImpl !== "function") throw new Error("This Node.js version does not provide fetch.");
@@ -919,54 +953,104 @@ export async function runDevSession(options) {
919
953
 
920
954
  let heartbeat = null;
921
955
  let task;
956
+ let context;
922
957
  let session;
958
+ let sessionPath;
923
959
  try {
924
- // Validate both host and key before resolving any task context.
960
+ // Validate both host and key before resolving any session context.
925
961
  await api.request("/api/profile", { signal: detachController.signal });
926
- const search = await api.request("/api/tasks/search", {
927
- method: "POST",
928
- body: { taskIdentifier: taskReference },
929
- signal: detachController.signal,
930
- });
931
- const tasks = search?.tasks || [];
932
- if (tasks.length === 0) throw new Error(`No accessible task matches '${taskReference}'.`);
933
- task = await selectOne({
934
- items: tasks,
935
- label: "tasks",
936
- describe: formatTask,
937
- interactive,
938
- ask,
939
- writeLine,
940
- });
941
-
942
- const sessionPath = `/api/projects/${encodeURIComponent(task.workspaceIdentifier)}/${encodeURIComponent(task.projectIdentifier)}/tasks/${encodeURIComponent(task.id)}/live-session`;
943
- const current = await api.request(`${sessionPath}/`, { signal: detachController.signal });
944
- session = current?.session || null;
945
- if (!session) {
946
- const repositoryResult = await api.request(`${sessionPath}/repositories`, { signal: detachController.signal });
947
- const repositories = repositoryResult?.repos || [];
948
- if (repositories.length === 0) {
949
- throw new Error("No linked repository is configured for this project.");
950
- }
951
- const repository = await selectOne({
952
- items: repositories,
953
- label: "repositories",
954
- describe: (item) => `${item.displayName || item.role}${item.defaultBranch ? ` · ${item.defaultBranch}` : ""}`,
955
- interactive,
956
- ask,
957
- writeLine,
958
- });
959
- writeLine(`Starting Dev Session with ${repository.displayName || repository.role}…`);
960
- const started = await api.request(`${sessionPath}/`, {
962
+ if (target.kind === "task") {
963
+ const search = await api.request("/api/tasks/search", {
961
964
  method: "POST",
962
- body: { runtimeRepositoryId: repository.id },
965
+ body: { taskIdentifier: target.taskReference },
963
966
  signal: detachController.signal,
964
- timeoutMs: 60_000,
965
967
  });
966
- session = started?.session;
967
- if (!session) throw new Error("Xevy accepted the request but returned no Dev Session.");
968
+ const tasks = search?.tasks || [];
969
+ if (tasks.length === 0) throw new Error(`No accessible task matches '${target.taskReference}'.`);
970
+ if (tasks.length > 1) {
971
+ throw new Error(`More than one task matches '${target.taskReference}'. Use the task UUID after 'task/'.`);
972
+ }
973
+ task = tasks[0];
974
+ context = { kind: "task", task };
975
+ sessionPath = `/api/projects/${encodeURIComponent(task.workspaceIdentifier)}/${encodeURIComponent(task.projectIdentifier)}/tasks/${encodeURIComponent(task.id)}/live-session`;
976
+ const current = await api.request(`${sessionPath}/`, { signal: detachController.signal });
977
+ session = current?.session || null;
978
+ if (!session) {
979
+ const repositoryResult = await api.request(`${sessionPath}/repositories`, { signal: detachController.signal });
980
+ const repositories = repositoryResult?.repos || [];
981
+ if (repositories.length === 0) {
982
+ throw new Error("No linked repository is configured for this project.");
983
+ }
984
+ const repository = await selectOne({
985
+ items: repositories,
986
+ label: "repositories",
987
+ describe: (item) => `${item.displayName || item.role}${item.defaultBranch ? ` · ${item.defaultBranch}` : ""}`,
988
+ interactive,
989
+ ask,
990
+ writeLine,
991
+ });
992
+ writeLine(`Starting Dev Session with ${repository.displayName || repository.role}…`);
993
+ const started = await api.request(`${sessionPath}/`, {
994
+ method: "POST",
995
+ body: { runtimeRepositoryId: repository.id },
996
+ signal: detachController.signal,
997
+ timeoutMs: 60_000,
998
+ });
999
+ session = started?.session;
1000
+ if (!session) throw new Error("Xevy accepted the request but returned no Dev Session.");
1001
+ } else {
1002
+ writeLine("Attaching to the existing Dev Session…");
1003
+ }
968
1004
  } else {
969
- writeLine("Attaching to the existing Dev Session…");
1005
+ const workspaceResult = await api.request("/api/workspaces", { signal: detachController.signal });
1006
+ const workspace = (workspaceResult?.workspaces || [])
1007
+ .find((item) => item.identifier === target.workspaceIdentifier);
1008
+ const project = workspace?.projects?.find((item) => item.identifier === target.projectIdentifier);
1009
+ if (!workspace || !project) {
1010
+ throw new Error(`No accessible project matches '${target.workspaceIdentifier}/${target.projectIdentifier}'.`);
1011
+ }
1012
+ context = { kind: "personal", workspace, project };
1013
+ const candidates = await api.request(
1014
+ `/api/agent/dev-session-candidates?projectId=${encodeURIComponent(project.id)}`,
1015
+ { signal: detachController.signal },
1016
+ );
1017
+ const existingSessionId = candidates?.personal?.existingSessionId || null;
1018
+ if (existingSessionId) {
1019
+ sessionPath = `/api/agent/dev-sessions/${encodeURIComponent(existingSessionId)}`;
1020
+ const current = await api.request(sessionPath, { signal: detachController.signal });
1021
+ session = current?.session || null;
1022
+ if (session) writeLine("Attaching to your existing personal Dev Session…");
1023
+ }
1024
+ if (!session) {
1025
+ const repositories = candidates?.repositories || [];
1026
+ if (repositories.length === 0) {
1027
+ throw new Error(candidates?.personal?.blocker || "No linked repository is configured for this project.");
1028
+ }
1029
+ const repository = await selectOne({
1030
+ items: repositories,
1031
+ label: "repositories",
1032
+ describe: (item) => `${item.displayName || item.role}${item.defaultBranch ? ` · ${item.defaultBranch}` : ""}`,
1033
+ interactive,
1034
+ ask,
1035
+ writeLine,
1036
+ });
1037
+ writeLine(`Starting personal Dev Session with ${repository.displayName || repository.role}…`);
1038
+ const started = await api.request("/api/agent/dev-sessions", {
1039
+ method: "POST",
1040
+ body: {
1041
+ target: {
1042
+ kind: "personal",
1043
+ projectId: project.id,
1044
+ runtimeRepositoryId: repository.id,
1045
+ },
1046
+ },
1047
+ signal: detachController.signal,
1048
+ timeoutMs: 60_000,
1049
+ });
1050
+ session = started?.session;
1051
+ if (!session?.id) throw new Error("Xevy accepted the request but returned no Dev Session.");
1052
+ sessionPath = `/api/agent/dev-sessions/${encodeURIComponent(session.id)}`;
1053
+ }
970
1054
  }
971
1055
 
972
1056
  let heartbeatFailures = 0;
@@ -996,15 +1080,19 @@ export async function runDevSession(options) {
996
1080
  sleep,
997
1081
  signal: detachController.signal,
998
1082
  });
999
- sessionSummary(task, session, base, writeLine);
1083
+ sessionSummary(context, session, base, writeLine);
1000
1084
 
1001
1085
  const nativeTerminal = options.nativeTerminal
1002
1086
  ?? (input === process.stdin && output === process.stdout);
1003
1087
  if (interactive && nativeTerminal) {
1004
- await attachNativeTerminalPersistently({
1088
+ const reattachTarget = context.kind === "task"
1089
+ ? `task/${task.taskCode || task.id}`
1090
+ : `${context.workspace.identifier}/${context.project.identifier}`;
1091
+ await attachNativeTerminalOnce({
1005
1092
  api,
1006
1093
  base,
1007
1094
  sessionPath,
1095
+ reattachHint: `Reattach with: xevy dev ${reattachTarget}`,
1008
1096
  input,
1009
1097
  output,
1010
1098
  signal: detachController.signal,
@@ -1014,7 +1102,12 @@ export async function runDevSession(options) {
1014
1102
  animateStatus: options.animateStatus,
1015
1103
  });
1016
1104
  detached = true;
1017
- return { task, session, detached: true };
1105
+ return { task, project: context.kind === "personal" ? context.project : null, session, detached: true };
1106
+ }
1107
+
1108
+ if (context.kind === "personal") {
1109
+ writeLine("Attached successfully. Rerun in an interactive terminal to open Pi.");
1110
+ return { task: null, project: context.project, session, detached: true };
1018
1111
  }
1019
1112
 
1020
1113
  const renderState = {
@@ -1044,7 +1137,7 @@ export async function runDevSession(options) {
1044
1137
 
1045
1138
  if (!interactive) {
1046
1139
  writeLine("Attached successfully. Rerun in an interactive terminal to prompt the agent.");
1047
- return { task, session, detached: true };
1140
+ return { task, project: null, session, detached: true };
1048
1141
  }
1049
1142
 
1050
1143
  while (!detached) {
@@ -1052,7 +1145,7 @@ export async function runDevSession(options) {
1052
1145
  if (detached) break;
1053
1146
  if (!prompt) continue;
1054
1147
  if (prompt === "/help") {
1055
- commandHelp(writeLine);
1148
+ commandHelp(writeLine, session.config?.runtimeMode !== "none" && Boolean(session.hostname));
1056
1149
  continue;
1057
1150
  }
1058
1151
  if (prompt === "/detach") {
@@ -1063,7 +1156,7 @@ export async function runDevSession(options) {
1063
1156
  const result = await api.request(`${sessionPath}/`, { signal: detachController.signal });
1064
1157
  if (!result?.session) throw new Error("No active Dev Session remains for this task.");
1065
1158
  session = result.session;
1066
- sessionSummary(task, session, base, writeLine);
1159
+ sessionSummary(context, session, base, writeLine);
1067
1160
  continue;
1068
1161
  }
1069
1162
  if (prompt === "/logs") {
@@ -1073,6 +1166,10 @@ export async function runDevSession(options) {
1073
1166
  continue;
1074
1167
  }
1075
1168
  if (prompt === "/open") {
1169
+ if (session.config?.runtimeMode === "none" || !session.hostname) {
1170
+ writeLine("This Dev Session has no web runtime or live preview.");
1171
+ continue;
1172
+ }
1076
1173
  await launchBrowser({ api, sessionPath, platform, spawnImpl, writeLaunchLine });
1077
1174
  continue;
1078
1175
  }
@@ -1161,10 +1258,15 @@ export async function runDevSession(options) {
1161
1258
  writeLine(`Agent turn failed: ${completed.errorMessage || "unknown error"}`);
1162
1259
  }
1163
1260
  }
1164
- return { task, session, detached: true };
1261
+ return { task, project: null, session, detached: true };
1165
1262
  } catch (error) {
1166
1263
  if (detached && /detached/i.test(error instanceof Error ? error.message : String(error))) {
1167
- return { task, session, detached: true };
1264
+ return {
1265
+ task,
1266
+ project: context?.kind === "personal" ? context.project : null,
1267
+ session,
1268
+ detached: true,
1269
+ };
1168
1270
  }
1169
1271
  throw new Error(redactSensitive(error instanceof Error ? error.message : String(error), secrets));
1170
1272
  } finally {
package/bin/xevy.mjs CHANGED
@@ -96,7 +96,7 @@ function usage() {
96
96
  xevy setup [options] Choose credentials, pi, skills, and MCP setup
97
97
  xevy update [--base u] Refresh the pi extensions + coding-agent skills/MCP
98
98
  xevy check [--base u] Report skill updates or missing coding-agent targets
99
- xevy dev <task> Attach to a remote task Dev Session
99
+ xevy dev <target> Attach to a remote task or personal Dev Session
100
100
 
101
101
  Options:
102
102
  --base <url> Xevy host (default: XEVY_BASE or ${DEFAULT_BASE})
@@ -118,7 +118,8 @@ Examples:
118
118
  npx @xevy/cli setup --credentials --mcp -a codex
119
119
  npx @xevy/cli setup --all -y
120
120
  npx @xevy/cli update
121
- npx @xevy/cli dev VI22-07
121
+ npx @xevy/cli dev task/VI22-07
122
+ npx @xevy/cli dev xevy/xevyai
122
123
  npx @xevy/cli
123
124
 
124
125
  Install globally to drop the npx prefix:
@@ -130,11 +131,12 @@ Install globally to drop the npx prefix:
130
131
  function devUsage() {
131
132
  console.log(`Xevy Dev Session
132
133
 
133
- xevy dev <task-id-or-code> [--base <url>]
134
+ xevy dev task/<task-id-or-code> [--base <url>]
135
+ xevy dev <workspace>/<project> [--base <url>]
134
136
 
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, then opens Pi's
137
- native interactive terminal inside the isolated remote workspace.
137
+ Connects this terminal to a remote Dev Session. The reserved task/ prefix
138
+ selects task work; a workspace/project target starts or resumes your personal
139
+ project session. Pi runs inside the isolated remote workspace.
138
140
 
139
141
  Terminal control:
140
142
  Ctrl+] Detach without stopping Pi or the Dev Session
@@ -159,7 +161,7 @@ function parseArgv(argv) {
159
161
  try {
160
162
  const parsed = parseDevCommandArgs(args);
161
163
  if (parsed.help) return { command: "dev-help" };
162
- return { command: "dev", taskReference: parsed.taskReference, base: parsed.base };
164
+ return { command: "dev", target: parsed.target, base: parsed.base };
163
165
  } catch (error) {
164
166
  die(error instanceof Error ? error.message : String(error));
165
167
  }
@@ -663,7 +665,7 @@ async function dev(opts) {
663
665
  await runDevSession({
664
666
  base,
665
667
  token,
666
- taskReference: opts.taskReference,
668
+ target: opts.target,
667
669
  });
668
670
  }
669
671
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xevy/cli",
3
- "version": "0.1.18",
3
+ "version": "0.1.21",
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": [