linkshell-cli 0.6.1 → 0.6.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "linkshell-cli",
-  "version": "0.6.1",
-  "description": "Remote terminal bridge for Claude Code / Codex / Gemini / Copilot — control from your phone",
+  "version": "0.6.3",
+  "description": "Follow, steer and approve the coding agents on your computer (Claude Code, Codex, Gemini, Copilot and more) from your phone",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -36,10 +36,10 @@
     "qrcode-terminal": "^0.12.0",
     "ws": "^8.18.1",
     "zod": "^3.24.3",
-    "@linkshell/gateway": "0.5.0",
+    "@linkshell/gateway": "0.5.3",
     "@linkshell/protocol": "0.4.10",
-    "@linkshell/wire": "0.1.0",
-    "@linkshell/host": "0.1.0"
+    "@linkshell/wire": "0.1.3",
+    "@linkshell/host": "0.1.2"
   },
   "optionalDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.128",

package/src/auth.ts

@@ -2,7 +2,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 
-const AUTH_DIR = join(homedir(), ".linkshell");
+const AUTH_DIR = process.env.LINKSHELL_HOME || join(homedir(), ".linkshell");
 const AUTH_FILE = join(AUTH_DIR, "auth.json");
 
 export interface AuthTokens {

package/src/commands/doctor.ts

@@ -1,6 +1,7 @@
 import { execSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { loadConfig, getConfigPath } from "../config.js";
+import { loadAuth } from "../auth.js";
+import { hostRuntimeOk, resolveGateway, withRunningHost } from "./host.js";
 
 const requireFromCli = createRequire(import.meta.url);
 
@@ -26,32 +27,32 @@ function which(bin: string): string | undefined {
   }
 }
 
-async function checkGateway(url: string): Promise<CheckResult> {
+async function checkGateway(name: string, url: string): Promise<CheckResult> {
   try {
-    const httpUrl = url.replace(/\/ws\/?$/, "").replace(/^wss:/, "https:").replace(/^ws:/, "http:");
+    const httpUrl = url.replace(/\/(ws|v2\/connect)\/?$/, "").replace(/\/$/, "").replace(/^wss:/, "https:").replace(/^ws:/, "http:");
     const start = Date.now();
     const res = await fetch(`${httpUrl}/healthz`, { signal: AbortSignal.timeout(5000) });
     const latency = Date.now() - start;
-    if (!res.ok) return { name: "Gateway", ok: false, detail: `HTTP ${res.status}` };
-    return { name: "Gateway", ok: true, detail: `reachable (${latency}ms)` };
+    if (!res.ok) return { name, ok: false, detail: `${url}: HTTP ${res.status}` };
+    return { name, ok: true, detail: `${url} answers (${latency}ms)` };
   } catch (e) {
-    return { name: "Gateway", ok: false, detail: e instanceof Error ? e.message : "unreachable" };
+    return { name, ok: false, detail: `${url}: ${e instanceof Error ? e.message : "unreachable"}` };
   }
 }
 
-export async function runDoctor(gatewayUrl?: string): Promise<void> {
-  const config = loadConfig();
-  const gateway = gatewayUrl ?? config.gateway;
+const AGENT_INSTALL: Record<string, string> = {
+  claude: "npm i -g @anthropic-ai/claude-code",
+  codex: "npm i -g @openai/codex",
+};
 
+export async function runDoctor(version: string, gatewayUrl?: string): Promise<void> {
   process.stdout.write("\n  LinkShell Doctor\n\n");
 
   const results: CheckResult[] = [];
 
   results.push(check("Node.js", () => {
-    const ver = process.versions.node;
-    const major = Number(ver.split(".")[0]);
-    if (major < 18) throw new Error(`v${ver} (need >= 18)`);
-    return `v${ver}`;
+    if (!hostRuntimeOk()) throw new Error(`v${process.versions.node} (the host needs 22.13 or newer)`);
+    return `v${process.versions.node}`;
   }));
 
   results.push(check("node-pty", () => {
@@ -69,32 +70,73 @@ export async function runDoctor(gatewayUrl?: string): Promise<void> {
     }
   }));
 
-  // Optional CLI hints — not required, since LinkShell now bridges a plain shell.
-  for (const [label, bin, hint] of [
-    ["Claude CLI (optional)", "claude", "npm i -g @anthropic-ai/claude-code"],
-    ["Codex CLI (optional)", "codex", "npm i -g @openai/codex"],
-  ] as const) {
-    const path = which(bin);
-    if (path) {
-      results.push({ name: label, ok: true, detail: `found (${path})` });
-    } else {
-      results.push({ name: label, ok: true, detail: `not installed — ${hint}` });
+  const host = await withRunningHost(async (client) => ({
+    info: await client.call("machine.info", {}),
+    gateway: await client.call("gateway.status", {}),
+  })).catch(() => undefined);
+
+  if (!host) {
+    results.push({ name: "Host", ok: false, detail: "not running — start it with: linkshell host --daemon" });
+    // Without the host, at least say whether the two main agents are on the PATH.
+    for (const [bin, hint] of Object.entries(AGENT_INSTALL)) {
+      const path = which(bin);
+      results.push({ name: `${bin} (optional)`, ok: true, detail: path ? `found (${path})` : `not installed — ${hint}` });
+    }
+  } else {
+    results.push(
+      host.info.hostVersion === version
+        ? { name: "Host", ok: true, detail: `running, ${version}` }
+        : {
+            name: "Host",
+            ok: false,
+            detail: `running ${host.info.hostVersion}, but this CLI is ${version} — update it with: linkshell host stop && linkshell host --daemon`,
+          },
+    );
+    // Agents as the host sees them: what the phone can actually start.
+    for (const agent of host.info.agents) {
+      if (!agent.installed) {
+        const hint = AGENT_INSTALL[agent.id];
+        if (hint) results.push({ name: `${agent.label} (optional)`, ok: true, detail: `not installed — ${hint}` });
+        continue;
+      }
+      const signedOut = agent.auth?.state === "missing";
+      const problem = agent.problem ?? (signedOut ? (agent.auth?.hint ?? "not logged in") : undefined);
+      results.push({ name: agent.label, ok: !problem, detail: `v${agent.version ?? "?"}${problem ? ` — ${problem}` : ""}` });
     }
   }
 
-  results.push(check("Config", () => {
-    const path = getConfigPath();
-    const cfg = loadConfig();
-    const keys = Object.keys(cfg).filter((k) => cfg[k as keyof typeof cfg] !== undefined);
-    if (keys.length === 0) return `${path} (empty — run: linkshell setup)`;
-    return `${path} (${keys.join(", ")})`;
-  }));
+  const auth = loadAuth();
+  results.push({
+    name: "Account",
+    ok: true,
+    detail: auth?.accessToken ? `logged in as ${auth.email || auth.userId}` : "not logged in (only the official gateway needs it: linkshell login)",
+  });
 
-  if (gateway) {
-    results.push(await checkGateway(gateway));
-  } else {
-    results.push({ name: "Gateway", ok: false, detail: "no gateway configured — run: linkshell setup" });
+  if (host) {
+    const gateway = host.gateway;
+    if (gateway.status === "online") {
+      const account = gateway.account ? `, account ${gateway.account.email ?? gateway.account.userId}` : "";
+      const paired = gateway.devices.length ? `, ${gateway.devices.length} paired device(s)` : "";
+      results.push({ name: "Gateway", ok: true, detail: `online ${gateway.url}${account}${paired}` });
+    } else if (gateway.status === "off") {
+      results.push({
+        name: "Gateway",
+        ok: false,
+        detail: "off, so a phone can't reach this computer — linkshell login (official gateway), or linkshell host --gateway <url>",
+      });
+    } else {
+      results.push({ name: "Gateway", ok: false, detail: `${gateway.status} ${gateway.url}${gateway.error ? ` — ${gateway.error.message}` : ""}` });
+    }
+  } else if (!gatewayUrl && hostRuntimeOk()) {
+    const { defaultHome } = await import("@linkshell/host");
+    const chosen = resolveGateway(defaultHome());
+    results.push(
+      chosen
+        ? await checkGateway("Gateway", chosen)
+        : { name: "Gateway", ok: false, detail: "none chosen — linkshell login (official gateway), or linkshell host --gateway <url>" },
+    );
   }
+  if (gatewayUrl) results.push(await checkGateway(host ? "Gateway (--gateway)" : "Gateway", gatewayUrl));
 
   for (const r of results) {
     const icon = r.ok ? "\x1b[32m✓\x1b[0m" : "\x1b[31m✗\x1b[0m";

package/src/commands/host.ts

@@ -1,12 +1,13 @@
 import { spawn } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import type { GatewayStatus } from "@linkshell/wire";
 import { getValidToken, isLoggedIn } from "../auth.js";
 import * as daemon from "../utils/daemon.js";
 
 // node:sqlite prints an ExperimentalWarning on load; it is expected here and
 // only confuses users. Must run before the host (and node:sqlite) is imported.
-function silenceSqliteWarning(): void {
+export function silenceSqliteWarning(): void {
   const emit = process.emitWarning.bind(process);
   process.emitWarning = ((warning: string | Error, ...rest: unknown[]) => {
     const message = typeof warning === "string" ? warning : warning.message;
@@ -30,7 +31,8 @@ export const OFFICIAL_GATEWAY = "wss://gateway.itool.tech";
 export function resolveGateway(home: string): string | undefined {
   const chosen = process.env.LINKSHELL_GATEWAY || readHostConfig(home).gateway;
   if (chosen === "off") return undefined;
-  if (chosen) return chosen;
+  // config.json is shared with the v1 bridge, whose gateway URLs end in /ws.
+  if (chosen) return chosen.replace(/\/ws\/?$/, "");
   return isLoggedIn() ? OFFICIAL_GATEWAY : undefined;
 }
 
@@ -52,9 +54,13 @@ export function writeHostConfig(home: string, config: HostConfig): void {
 }
 
 /** The host keeps its state in node:sqlite, unflagged from Node 22.13. */
-export function assertHostRuntime(): void {
+export function hostRuntimeOk(): boolean {
   const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
-  if (major > 22 || (major === 22 && minor >= 13)) return;
+  return major > 22 || (major === 22 && minor >= 13);
+}
+
+export function assertHostRuntime(): void {
+  if (hostRuntimeOk()) return;
   process.stderr.write(
     `\n  LinkShell's host needs Node.js 22.13 or newer (this is ${process.version}).\n` +
       "  Upgrade Node (for example: nvm install 22, or brew upgrade node), then try again.\n\n",
@@ -83,12 +89,13 @@ export async function runHostForeground(version: string): Promise<void> {
   const devPort = process.env.LINKSHELL_DEV_PORT ? Number(process.env.LINKSHELL_DEV_PORT) : undefined;
   // Where devices reach this machine from outside the LAN. The account from
   // `linkshell login`, if any, lets that account's devices in without pairing.
-  const gatewayUrl = resolveGateway(host.defaultHome());
+  // Asked again on `gateway.refresh`, so login, logout and `--gateway` apply to a running host.
+  const home = host.defaultHome();
   const running = await host.startHost({
     version,
     env,
     log,
-    gateway: gatewayUrl ? { url: gatewayUrl, token: async () => (await getValidToken()) ?? undefined } : undefined,
+    gateway: { url: () => resolveGateway(home), token: async () => (await getValidToken()) ?? undefined },
     tcpPort: devPort,
     claudeCommand: process.env.LINKSHELL_CLAUDE_COMMAND || undefined,
     claudeAdapter: adapter ? { command: adapter, args: [] } : undefined,
@@ -127,6 +134,89 @@ export async function ensureHostRunning(): Promise<string> {
   throw new Error(`LinkShell host did not start; see ${daemon.getLogFile("host")}`);
 }
 
+type HostClient = Awaited<ReturnType<Awaited<ReturnType<typeof loadHost>>["connectHost"]>>;
+
+/** Runs `use` against the running host; undefined when there is none. */
+export async function withRunningHost<T>(use: (client: HostClient) => Promise<T>): Promise<T | undefined> {
+  if (!hostRuntimeOk()) return undefined;
+  const host = await loadHost();
+  const { hostSocket } = host.hostPaths();
+  if (!(await host.isHostRunning(hostSocket))) return undefined;
+  const client = await host.connectHost(hostSocket);
+  try {
+    return await use(client);
+  } finally {
+    client.close();
+  }
+}
+
+/**
+ * Has the running host apply the current gateway choice and account, then
+ * waits (up to `waitMs`) for it to come online or be refused.
+ */
+export async function refreshGateway(waitMs: number): Promise<GatewayStatus | undefined> {
+  return withRunningHost(async (client) => {
+    let status: GatewayStatus;
+    try {
+      status = await client.call("gateway.refresh", {});
+    } catch {
+      // A host from before 0.6.3 (still running after an upgrade) only reads its gateway at start.
+      process.stderr.write("  The running host is older than this CLI. Restart it to apply this (stops running agent turns):\n");
+      process.stderr.write("    linkshell host stop && linkshell host --daemon\n");
+      return client.call("gateway.status", {});
+    }
+    const deadline = Date.now() + waitMs;
+    while (status.status === "connecting" && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 200));
+      status = await client.call("gateway.status", {});
+    }
+    return status;
+  });
+}
+
+export function describeGateway(gateway: GatewayStatus): string {
+  if (gateway.status === "off") return "off (linkshell login for the official one, or linkshell host --gateway <url>)";
+  const account = gateway.account ? `, account ${gateway.account.email ?? gateway.account.userId}` : "";
+  const problem = gateway.error ? `  ⚠ ${gateway.error.message}` : "";
+  return `${gateway.status} ${gateway.url}${account}${problem}`;
+}
+
+/** After `linkshell login`: this computer joins the gateway its account is for. */
+export async function joinGatewayAfterLogin(plan: "pro" | "free"): Promise<void> {
+  const out = (line: string) => process.stderr.write(`  ${line}\n`);
+  if (!hostRuntimeOk()) {
+    out(`The LinkShell host needs Node.js 22.13 or newer (this is ${process.version}); upgrade Node, then: linkshell host --daemon\n`);
+    return;
+  }
+  const host = await loadHost();
+  const chosen = process.env.LINKSHELL_GATEWAY || readHostConfig(host.defaultHome()).gateway;
+  if (chosen === "off") {
+    out("The gateway is turned off on this computer. To use the official one: linkshell host --gateway default\n");
+    return;
+  }
+  if (!chosen && plan !== "pro") {
+    // A running host now gets the gateway's own answer, instead of an old login's.
+    await refreshGateway(0);
+    out("The official gateway needs a Pro subscription: https://itool.tech");
+    out("Or use your own gateway: linkshell host --gateway <url>, then linkshell pair\n");
+    return;
+  }
+  await ensureHostRunning();
+  const gateway = await refreshGateway(15_000);
+  const where = chosen ? (gateway?.url ?? chosen) : "the official gateway";
+  if (gateway?.status === "online") {
+    out(`\x1b[32m✓\x1b[0m This computer is online on ${where}.`);
+    out(
+      gateway.account
+        ? "  Open LinkShell on your phone and sign in with the same account: it shows up there, no pairing needed.\n"
+        : "  Pair your phone with: linkshell pair\n",
+    );
+  } else {
+    out(`\x1b[31m✗\x1b[0m Not connected to ${where}${gateway?.error ? `: ${gateway.error.message}` : " yet"}`);
+    out("  Check again with: linkshell host status\n");
+  }
+}
+
 export async function printHostStatus(): Promise<void> {
   const host = await loadHost();
   const { hostSocket } = host.hostPaths();
@@ -153,15 +243,9 @@ export async function printHostStatus(): Promise<void> {
     const active = sessions.filter((s) => s.state === "running" || s.state === "waiting");
     process.stdout.write(`  Sessions: ${sessions.length} known, ${active.length} active\n`);
     const gateway = await client.call("gateway.status", {});
-    if (gateway.status === "off") {
-      process.stdout.write("  Gateway:  off (linkshell login for the official one, or linkshell host --gateway <url>)\n");
-    } else {
-      const account = gateway.account ? `, account ${gateway.account.email ?? gateway.account.userId}` : "";
-      const problem = gateway.error ? `  ⚠ ${gateway.error.message}` : "";
-      process.stdout.write(`  Gateway:  ${gateway.status} ${gateway.url}${account}${problem}\n`);
-      for (const device of gateway.devices) {
-        process.stdout.write(`    ${device.online ? "●" : "○"} ${device.name}  paired ${new Date(device.pairedAt).toLocaleDateString()}\n`);
-      }
+    process.stdout.write(`  Gateway:  ${describeGateway(gateway)}\n`);
+    for (const device of gateway.devices) {
+      process.stdout.write(`    ${device.online ? "●" : "○"} ${device.name}  paired ${new Date(device.pairedAt).toLocaleDateString()}\n`);
     }
   } finally {
     client.close();
@@ -174,10 +258,14 @@ interface LaunchSpec {
   env?: Record<string, string>;
 }
 
-function runChild(launch: LaunchSpec, onSpawn?: (child: import("node:child_process").ChildProcess) => void): Promise<number> {
+function runChild(
+  launch: LaunchSpec,
+  baseEnv: NodeJS.ProcessEnv,
+  onSpawn?: (child: import("node:child_process").ChildProcess) => void,
+): Promise<number> {
   const child = spawn(launch.command, launch.args, {
     stdio: "inherit",
-    env: { ...process.env, ...launch.env },
+    env: { ...baseEnv, ...launch.env },
   });
   onSpawn?.(child);
   // The terminal delivers Ctrl-C to the whole foreground group; the agent handles it.
@@ -231,6 +319,8 @@ export async function runAgentShim(agent: string, args: string[]): Promise<void>
   const host = await loadHost();
   const socket = await ensureHostRunning();
   const client = await host.connectHost(socket);
+  // Run from inside a Claude Code session, the agent must not become its child.
+  const env = host.withoutClaudeSession(process.env);
   let launch: LaunchSpec & { sessionId?: string };
   try {
     launch = await client.call("desktop.launch", { agent, args, cwd: process.cwd() });
@@ -242,7 +332,7 @@ export async function runAgentShim(agent: string, args: string[]): Promise<void>
   if (!launch.sessionId) {
     // Multi-client agents (Codex): the TUI simply joins the shared server.
     client.close();
-    process.exit(await runChild(launch));
+    process.exit(await runChild(launch, env));
   }
 
   const sessionId = launch.sessionId;
@@ -260,7 +350,7 @@ export async function runAgentShim(agent: string, args: string[]): Promise<void>
 
   for (;;) {
     yielded = false;
-    const code = await runChild(launch, (spawned) => (child = spawned));
+    const code = await runChild(launch, env, (spawned) => (child = spawned));
     if (!yielded) {
       // The user quit the TUI: the session stays available on every device.
       client.close();

package/src/commands/logout.ts

@@ -1,12 +1,20 @@
 import { clearAuth, loadAuth } from "../auth.js";
+import { refreshGateway, withRunningHost } from "./host.js";
 
-export function runLogout(): void {
+export async function runLogout(): Promise<void> {
   const auth = loadAuth();
   if (!auth || !auth.accessToken) {
     process.stderr.write("\n  Not currently logged in.\n\n");
     return;
   }
 
+  const before = await withRunningHost((client) => client.call("gateway.status", {}));
   clearAuth();
-  process.stderr.write(`\n  \x1b[32m✓\x1b[0m Logged out${auth.email ? ` (${auth.email})` : ""}.\n\n`);
+  process.stderr.write(`\n  \x1b[32m✓\x1b[0m Logged out${auth.email ? ` (${auth.email})` : ""}.\n`);
+  // A running host leaves the account's gateway now, not at its next reconnect.
+  const after = await refreshGateway(0);
+  if (before && before.status !== "off" && after?.status === "off") {
+    process.stderr.write("  This computer is off the official gateway; the host and its sessions keep running.\n");
+  }
+  process.stderr.write("\n");
 }

package/src/commands/upgrade.ts

@@ -1,5 +1,6 @@
 import { execSync } from "node:child_process";
 import { createRequire } from "node:module";
+import { withRunningHost } from "./host.js";
 
 const require = createRequire(import.meta.url);
 const pkg = require("../../../../package.json") as { version: string };
@@ -31,6 +32,14 @@ async function fetchLatestVersion(): Promise<string | null> {
   }
 }
 
+/** The background host keeps running the version it was started with. */
+async function noteRunningHost(latest: string): Promise<void> {
+  const running = await withRunningHost((client) => client.call("machine.info", {})).catch(() => undefined);
+  if (!running || running.hostVersion === latest) return;
+  process.stderr.write(`  The running host is still ${running.hostVersion}. Restart it to use ${latest} (stops running agent turns):\n`);
+  process.stderr.write("    linkshell host stop && linkshell host --daemon\n\n");
+}
+
 export async function runUpgrade(): Promise<void> {
   const current = pkg.version;
   process.stderr.write(`\n  Current version: ${current}\n`);
@@ -55,6 +64,7 @@ export async function runUpgrade(): Promise<void> {
     try {
       execSync("brew upgrade linkshell", { stdio: "inherit", timeout: 120_000 });
       process.stderr.write("\n  \x1b[32m✓\x1b[0m Upgraded successfully.\n\n");
+      await noteRunningHost(latest);
     } catch {
       process.stderr.write("\n  \x1b[31m✗\x1b[0m Homebrew upgrade failed. Try manually:\n");
       process.stderr.write("    brew upgrade linkshell\n\n");
@@ -65,6 +75,7 @@ export async function runUpgrade(): Promise<void> {
     try {
       execSync("npm install -g linkshell-cli@latest", { stdio: "inherit", timeout: 120_000 });
       process.stderr.write("\n  \x1b[32m✓\x1b[0m Upgraded successfully.\n\n");
+      await noteRunningHost(latest);
     } catch {
       process.stderr.write("\n  \x1b[31m✗\x1b[0m npm upgrade failed. Try manually:\n");
       process.stderr.write("    npm install -g linkshell-cli@latest\n\n");

package/src/config.ts

@@ -14,7 +14,7 @@ export interface LinkShellConfig {
   rows?: number;
 }
 
-const CONFIG_DIR = join(homedir(), ".linkshell");
+const CONFIG_DIR = process.env.LINKSHELL_HOME || join(homedir(), ".linkshell");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
 
 export function loadConfig(): LinkShellConfig {