@dhf-claude/grix 0.1.8 → 0.1.9

package/README.md

@@ -1,35 +1,43 @@
 # @dhf-claude/grix
 
-This integration connects Claude to Grix ([https://grix.dhf.pub/](https://grix.dhf.pub/)) so you can manage Claude from the website, with mobile PWA support.
+Connect local Claude Code to Grix so you can use Claude from the Grix website or mobile PWA.
 
-## Quick Start
+## Before You Start
+
+Make sure this machine already has:
 
-### 1. Install globally
+- Claude Code installed, and the `claude` command works in your terminal
+- A valid Claude login on this machine
+- The 3 connection values from the Grix console:
+  - `wsUrl`
+  - `agentId`
+  - `apiKey`
+
+If Claude is not logged in yet, run:
 
 ```bash
-npm install -g @dhf-claude/grix
+claude auth login
 ```
 
-### 2. Install the background service (first time)
+## Quick Start
 
-Get these 3 values from the Grix console first:
+### 1. Install the package
 
-- `wsUrl`
-- `agentId`
-- `apiKey`
+```bash
+npm install -g @dhf-claude/grix
+```
 
-Then run:
+### 2. Install and start the background service
 
 ```bash
 grix-claude install --ws-url <ws_url> --agent-id <agent_id> --api-key <api_key>
 ```
 
-This command will automatically:
+This will:
 
-- Save connection settings
+- Save your connection settings locally
 - Install a user-level background service
-- Start the local `daemon` immediately
-- Let `daemon` handle session startup, resume, and message relay
+- Start the local service immediately
 
 Supported background service managers:
 
@@ -37,7 +45,25 @@ Supported background service managers:
 - Linux: `systemd --user`
 - Windows: Task Scheduler
 
-## Commands you will usually use
+### 3. Start a Claude session from Grix
+
+Open the related Grix private chat and do either of these:
+
+- If Grix shows an open-workspace card, use that card
+- Or send:
+
+```text
+/grix open <your_working_directory>
+```
+
+The background service will start or resume the Claude session for that directory.
+
+Important:
+
+- One Grix private chat is bound to one working directory
+- After a chat is bound, that same chat cannot switch to another directory
+
+## Commands You Will Usually Use
 
 ```bash
 grix-claude status
@@ -47,98 +73,105 @@ grix-claude start
 grix-claude uninstall
 ```
 
-- `status` checks service and connection status
-- `restart` restarts after config changes
-- `stop` temporarily stops the background service
-- `start` starts the background service again
-- `uninstall` removes the background startup entry
+- `status`: show service and connection status
+- `restart`: restart after config changes or troubleshooting
+- `stop`: stop the background service
+- `start`: start it again
+- `uninstall`: remove the background startup entry
 
-## If you only want a temporary foreground run
+## Commands in Grix Chat
 
-You can run without installing a background service:
+Use these in the related Grix private chat:
 
-```bash
-grix-claude --ws-url <ws_url> --agent-id <agent_id> --api-key <api_key>
-```
+| Command | Purpose |
+| --- | --- |
+| `/grix open <working_directory>` | Start or resume a Claude session for that directory |
+| `/grix status` | Show current session status |
+| `/grix where` | Show the current bound directory |
+| `/grix stop` | Stop the current Claude session |
 
-If config is already saved locally, you can also just run:
+## Commands You Run Inside Claude
 
-```bash
-grix-claude
-```
+If you are already inside the Claude terminal session, use the same `/grix ...` command family:
 
-## How to start a Claude session
+| Command | Purpose |
+| --- | --- |
+| `/grix status` | Show current connection and status hints |
+| `/grix access` | Show current access control state |
+| `/grix access pair <code>` | Approve a pairing code |
+| `/grix access deny <code>` | Reject a pairing code |
+| `/grix access allow <sender_id>` | Add a sender to the allowlist |
+| `/grix access remove <sender_id>` | Remove a sender from the allowlist |
+| `/grix access policy <allowlist\|open\|disabled>` | Change access policy |
 
-Send this in the related Grix private chat:
+Access changes should be typed by you in the Claude terminal, not driven by messages from other people in chat.
 
-```text
-open <your_working_directory>
-```
+## Approvals and Questions
 
-`daemon` will start or resume the matching Claude session for that directory.
+When Claude needs confirmation or needs more information, Grix will show interactive cards.
 
-If you are already inside Claude, run:
+- For approvals, click the card buttons to approve or reject
+- For questions, fill the card and submit
+- For browser-based sign-in steps, open the link from the card and then return to the card to finish or cancel
 
-```text
-/grix:status
-```
+These cards are the normal user flow. Legacy text fallback commands are not part of normal use anymore.
 
-If the worker is attached to daemon, the link is healthy.
+## Temporary Foreground Run
 
-## Common commands inside Claude
+If you do not want to install a background service, you can run in the foreground:
 
-| Command | Purpose |
-| --- | --- |
-| `/grix:status` | Check current connection status |
-| `/grix:access` | Check current access control |
-| `/grix:access pair <code>` | Allow a new private-chat sender |
-| `/grix:access policy <allowlist\|open\|disabled>` | Switch access policy |
+```bash
+grix-claude --ws-url <ws_url> --agent-id <agent_id> --api-key <api_key>
+```
 
-Connection parameters are now managed only through local CLI, not from inside Claude sessions.
+If config is already saved locally, you can also just run:
 
-## Approvals and questions
+```bash
+grix-claude
+```
 
-When Claude needs your confirmation or more information, messages are sent back to Grix.
+## File Sending
 
-Interactive cards are used by default:
+Claude can send local files back to Grix.
 
-- For approvals, click approve/reject on the card
-- For questions, fill the card and submit
+- Maximum size per file: `50MB`
+- Common image, video, document, archive, and text formats are supported
 
-Text commands are still available as fallback:
+## Troubleshooting
 
-```text
-yes <request_id>
-no <request_id>
-/grix-question <request_id> your_answer
+### Check service status
+
+```bash
+grix-claude status
 ```
 
-- Use manual text input only for debugging, troubleshooting, or when cards are unavailable
+### If Claude login expired
 
-## File sending
+```bash
+claude auth login
+```
 
-Claude can send local files back to Grix. Maximum file size is 50MB, and only common image/video/document formats are supported.
+Then retry from Grix.
 
-## Log troubleshooting
+### Session log path
 
-Each AIBot session ID has an independent log file:
+Each Grix chat session has its own log file:
 
 ```text
 ~/.claude/grix-claude-daemon/sessions/<aibot_session_id>/logs/daemon-session.log
 ```
 
-This log records full Claude scheduling flow for that session, including:
+This log is the best place to check when:
 
-- Worker process state changes and PID
-- Process relaunch after exit
-- Message delivery and result callbacks
-- Connectivity probes and timeout decisions
+- Claude does not reply
+- Claude keeps restarting
+- Messages are not delivered back to Grix
 
-Full troubleshooting steps:
+More details:
 
 - `docs/session-log-troubleshooting.md`
 
-## CLI commands
+## CLI Reference
 
 ```text
 grix-claude install [options]
@@ -150,9 +183,12 @@ grix-claude uninstall [options]
 grix-claude [options]
 ```
 
-`install` is the recommended default. The plain `grix-claude [options]` command is better for temporary foreground runs or debugging.
+Recommended default:
 
-## Common options
+- Use `install` for normal long-running use
+- Use plain `grix-claude` only for temporary foreground runs or debugging
+
+## Common Options
 
 ```text
 --ws-url <value>      Grix Agent API WebSocket URL
@@ -165,35 +201,46 @@ grix-claude [options]
 --help, -h            show help
 ```
 
-- On first `install` or first foreground run, pass full connection parameters
-- If config has already been saved locally, you can omit connection parameters
-- Use `--data-dir` to isolate data directories across environments
+Notes:
+
+- On first `install` or first foreground run, pass the full connection parameters
+- If config is already saved locally, you can omit connection parameters
+- Use `--data-dir` if you want a separate data directory for another environment
 - `--show-claude` currently supports macOS Terminal only
 
-If Claude seems stuck on the startup confirmation page during development, add `--show-claude` so daemon opens the Claude session in a visible Terminal window.
+## For Developers
 
-## Auto-build during development
+If you are changing code in this repository:
 
-If you are changing code in this repository, run:
+```bash
+npm run dev:build
+```
+
+This keeps local build artifacts up to date.
+
+To start `grix-claude` against the local development environment:
 
 ```bash
 npm run dev
 ```
 
-It continuously watches source changes and builds the latest artifacts to:
+This uses a separate local data directory so it does not overwrite the production daemon state.
 
-- `dist/index.js`
-- `dist/daemon.js`
+To start `grix-claude` against the current production environment:
 
-For local integration testing, run this in another terminal:
+```bash
+npm run prod
+```
+
+This uses the standard production daemon state directory.
+
+To run the daemon locally in another terminal:
 
 ```bash
 npm run daemon
 ```
 
-Then both the daemon process and the worker loaded in Claude sessions will use the latest local build artifacts.
-
-If you want `npm run daemon` to read connection parameters directly from environment variables, run:
+If you want `npm run daemon` to read connection values from environment variables:
 
 ```bash
 GRIX_CLAUDE_ENDPOINT='ws://127.0.0.1:27189/v1/agent-api/ws?agent_id=<agent_id>' \
@@ -202,4 +249,4 @@ GRIX_CLAUDE_API_KEY='<api_key>' \
 npm run daemon -- --no-launch
 ```
 
-`GRIX_CLAUDE_WS_URL` is still supported; if both are provided, daemon prefers environment variable values.
+`GRIX_CLAUDE_WS_URL` is still supported. If both are provided, the daemon prefers the newer environment variable values.

package/cli/prod-runner.js

@@ -0,0 +1,163 @@
+import os from "node:os";
+import process from "node:process";
+import { run as runCli } from "./main.js";
+import { ServiceManager } from "../server/service/service-manager.js";
+import { inspectDaemonProcessState } from "../server/daemon/process-state.js";
+import { terminateProcessTree, waitForProcessExit } from "../server/process-control.js";
+import {
+  buildRuntimeArgs,
+  createManagedCommandEnv,
+  resolveRuntimeTarget,
+} from "./runtime-targets.js";
+
+const PROCESS_EXIT_TIMEOUT_MS = 5000;
+
+function printLine(message, print = (line) => process.stdout.write(`${line}\n`)) {
+  if (typeof print === "function") {
+    print(String(message ?? ""));
+  }
+}
+
+function didTargetStop(result) {
+  return Boolean(result?.serviceStopped || result?.processTerminated);
+}
+
+export async function stopRuntimeTarget(
+  target,
+  {
+    serviceManager,
+    inspectDaemonProcessStateImpl = inspectDaemonProcessState,
+    terminateProcessTreeImpl = terminateProcessTree,
+    waitForProcessExitImpl = waitForProcessExit,
+    platform = process.platform,
+  } = {},
+) {
+  if (!target?.dataDir) {
+    throw new Error("runtime target dataDir is required");
+  }
+  if (!serviceManager) {
+    throw new Error("serviceManager is required");
+  }
+
+  const status = await serviceManager.status({
+    dataDir: target.dataDir,
+  });
+  const serviceStopped = Boolean(status?.installed);
+  if (serviceStopped) {
+    await serviceManager.stop({
+      dataDir: target.dataDir,
+    });
+  }
+
+  const state = await inspectDaemonProcessStateImpl({
+    dataDir: target.dataDir,
+  });
+  const pid = Number(state?.pid ?? 0);
+  if (!state?.running || !Number.isFinite(pid) || pid <= 0) {
+    return {
+      target,
+      serviceStopped,
+      processTerminated: false,
+      pid,
+      running: Boolean(state?.running),
+    };
+  }
+
+  await terminateProcessTreeImpl(pid, {
+    platform,
+  });
+  const exited = await waitForProcessExitImpl(pid, {
+    timeoutMs: PROCESS_EXIT_TIMEOUT_MS,
+  });
+  if (!exited) {
+    throw new Error(`failed to stop ${target.name} daemon pid=${pid}`);
+  }
+
+  return {
+    target,
+    serviceStopped,
+    processTerminated: true,
+    pid,
+    running: false,
+  };
+}
+
+export async function runProdSwitch(
+  env = process.env,
+  {
+    runCliImpl = runCli,
+    serviceManager = null,
+    homeDir = os.homedir(),
+    print = (line) => process.stdout.write(`${line}\n`),
+    inspectDaemonProcessStateImpl = inspectDaemonProcessState,
+    terminateProcessTreeImpl = terminateProcessTree,
+    waitForProcessExitImpl = waitForProcessExit,
+    platform = process.platform,
+  } = {},
+) {
+  const runtimeEnv = createManagedCommandEnv(env);
+  const manager = serviceManager || new ServiceManager({
+    env: runtimeEnv,
+    homeDir,
+  });
+  const devTarget = resolveRuntimeTarget("dev", { homeDir });
+  const prodTarget = resolveRuntimeTarget("prod", { homeDir });
+
+  printLine("正在停止 dev...", print);
+  const devStopResult = await stopRuntimeTarget(devTarget, {
+    serviceManager: manager,
+    inspectDaemonProcessStateImpl,
+    terminateProcessTreeImpl,
+    waitForProcessExitImpl,
+    platform,
+  });
+  printLine(
+    didTargetStop(devStopResult)
+      ? "dev 已停止。"
+      : "dev 没有运行，无需处理。",
+    print,
+  );
+
+  printLine("正在清理旧的 prod 进程...", print);
+  const prodStopResult = await stopRuntimeTarget(prodTarget, {
+    serviceManager: manager,
+    inspectDaemonProcessStateImpl,
+    terminateProcessTreeImpl,
+    waitForProcessExitImpl,
+    platform,
+  });
+  printLine(
+    didTargetStop(prodStopResult)
+      ? "旧的 prod 进程已清理。"
+      : "没有发现旧的 prod 进程。",
+    print,
+  );
+
+  const prodStatus = await manager.status({
+    dataDir: prodTarget.dataDir,
+  });
+  const subcommand = prodStatus.installed ? "start" : "install";
+  printLine(
+    subcommand === "install"
+      ? "正在安装并启动后台服务..."
+      : "正在启动后台服务...",
+    print,
+  );
+  const exitCode = await runCliImpl([
+    subcommand,
+    ...buildRuntimeArgs(prodTarget),
+  ], runtimeEnv, {
+    serviceManager: manager,
+  });
+  if (Number(exitCode ?? 0) !== 0) {
+    throw new Error(`prod command failed with exit code ${exitCode}`);
+  }
+  printLine("prod 已切到后台运行。", print);
+
+  return {
+    devStopResult,
+    prodStopResult,
+    prodTarget,
+    subcommand,
+  };
+}

package/cli/prod-runner.test.js

@@ -0,0 +1,195 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+import {
+  buildRuntimeArgs,
+  createManagedCommandEnv,
+  resolveRuntimeTarget,
+} from "./runtime-targets.js";
+import { runProdSwitch, stopRuntimeTarget } from "./prod-runner.js";
+
+test("createManagedCommandEnv removes connection overrides", () => {
+  const env = createManagedCommandEnv({
+    KEEP_ME: "1",
+    GRIX_CLAUDE_WS_URL: "ws://stale",
+    GRIX_CLAUDE_ENDPOINT: "ws://stale-endpoint",
+    GRIX_CLAUDE_AGENT_ID: "stale-agent",
+    GRIX_CLAUDE_API_KEY: "stale-key",
+    GRIX_CLAUDE_OUTBOUND_TEXT_CHUNK_LIMIT: "4096",
+    GRIX_CLAUDE_TEXT_CHUNK_LIMIT: "4096",
+  });
+
+  assert.equal(env.KEEP_ME, "1");
+  assert.equal("GRIX_CLAUDE_WS_URL" in env, false);
+  assert.equal("GRIX_CLAUDE_ENDPOINT" in env, false);
+  assert.equal("GRIX_CLAUDE_AGENT_ID" in env, false);
+  assert.equal("GRIX_CLAUDE_API_KEY" in env, false);
+  assert.equal("GRIX_CLAUDE_OUTBOUND_TEXT_CHUNK_LIMIT" in env, false);
+  assert.equal("GRIX_CLAUDE_TEXT_CHUNK_LIMIT" in env, false);
+});
+
+test("resolveRuntimeTarget builds the expected prod args", () => {
+  const target = resolveRuntimeTarget("prod", {
+    homeDir: "/tmp/grix-home",
+  });
+
+  assert.deepEqual(buildRuntimeArgs(target), [
+    "--data-dir",
+    path.join("/tmp/grix-home", ".claude", "grix-claude-daemon"),
+    "--ws-url",
+    "wss://clawpool.dhf.pub/v1/agent-api/ws?agent_id=2035513096339984384",
+    "--agent-id",
+    "2035513096339984384",
+    "--api-key",
+    "ak_2035513096339984384_wyIkUkt9FyEZFJGHyvWHPu7ZOXkpj0KM",
+  ]);
+});
+
+test("stopRuntimeTarget stops installed service before killing a remaining daemon pid", async () => {
+  const calls = [];
+  const target = {
+    name: "dev",
+    dataDir: "/tmp/grix-dev",
+  };
+
+  const result = await stopRuntimeTarget(target, {
+    serviceManager: {
+      async status({ dataDir }) {
+        calls.push(["status", dataDir]);
+        return { installed: true };
+      },
+      async stop({ dataDir }) {
+        calls.push(["stop", dataDir]);
+      },
+    },
+    async inspectDaemonProcessStateImpl({ dataDir }) {
+      calls.push(["inspect", dataDir]);
+      return { running: true, pid: 4321 };
+    },
+    async terminateProcessTreeImpl(pid, { platform }) {
+      calls.push(["terminate", pid, platform]);
+    },
+    async waitForProcessExitImpl(pid, { timeoutMs }) {
+      calls.push(["wait", pid, timeoutMs]);
+      return true;
+    },
+    platform: "darwin",
+  });
+
+  assert.deepEqual(calls, [
+    ["status", "/tmp/grix-dev"],
+    ["stop", "/tmp/grix-dev"],
+    ["inspect", "/tmp/grix-dev"],
+    ["terminate", 4321, "darwin"],
+    ["wait", 4321, 5000],
+  ]);
+  assert.equal(result.serviceStopped, true);
+  assert.equal(result.processTerminated, true);
+});
+
+test("runProdSwitch stops dev and installs prod service when prod is not installed", async () => {
+  const serviceCalls = [];
+  const cliCalls = [];
+  const prints = [];
+  const prodDir = path.join("/tmp/grix-home", ".claude", "grix-claude-daemon");
+  const devDir = path.join("/tmp/grix-home", ".claude", "grix-claude-daemon-dev");
+
+  await runProdSwitch({
+    GRIX_CLAUDE_AGENT_ID: "stale-agent",
+    KEEP_ME: "1",
+  }, {
+    homeDir: "/tmp/grix-home",
+    print(line) {
+      prints.push(String(line));
+    },
+    serviceManager: {
+      async status({ dataDir }) {
+        serviceCalls.push(["status", dataDir]);
+        return { installed: dataDir === devDir ? false : false };
+      },
+    },
+    async inspectDaemonProcessStateImpl({ dataDir }) {
+      serviceCalls.push(["inspect", dataDir]);
+      if (dataDir === devDir) {
+        return { running: true, pid: 2222 };
+      }
+      return { running: false, pid: 0 };
+    },
+    async terminateProcessTreeImpl(pid) {
+      serviceCalls.push(["terminate", pid]);
+    },
+    async waitForProcessExitImpl(pid) {
+      serviceCalls.push(["wait", pid]);
+      return true;
+    },
+    async runCliImpl(argv, env, deps) {
+      cliCalls.push({ argv, env, deps });
+      return 0;
+    },
+  });
+
+  assert.deepEqual(serviceCalls, [
+    ["status", devDir],
+    ["inspect", devDir],
+    ["terminate", 2222],
+    ["wait", 2222],
+    ["status", prodDir],
+    ["inspect", prodDir],
+    ["status", prodDir],
+  ]);
+  assert.equal(cliCalls.length, 1);
+  assert.equal(cliCalls[0].argv[0], "install");
+  assert.equal(cliCalls[0].argv.includes(prodDir), true);
+  assert.equal("GRIX_CLAUDE_AGENT_ID" in cliCalls[0].env, false);
+  assert.equal(cliCalls[0].env.KEEP_ME, "1");
+  assert.ok(cliCalls[0].deps.serviceManager);
+  assert.match(prints.join("\n"), /dev 已停止/u);
+  assert.match(prints.join("\n"), /安装并启动后台服务/u);
+});
+
+test("runProdSwitch starts existing prod service after cleaning old prod runtime", async () => {
+  const cliCalls = [];
+  const prodDir = path.join("/tmp/grix-home-2", ".claude", "grix-claude-daemon");
+  const devDir = path.join("/tmp/grix-home-2", ".claude", "grix-claude-daemon-dev");
+  const installStateByDir = new Map([
+    [devDir, true],
+    [prodDir, true],
+  ]);
+
+  await runProdSwitch({}, {
+    homeDir: "/tmp/grix-home-2",
+    print() {},
+    serviceManager: {
+      async status({ dataDir }) {
+        return { installed: installStateByDir.get(dataDir) === true };
+      },
+      async stop() {},
+    },
+    async inspectDaemonProcessStateImpl({ dataDir }) {
+      if (dataDir === prodDir) {
+        return { running: true, pid: 3333 };
+      }
+      return { running: false, pid: 0 };
+    },
+    async terminateProcessTreeImpl() {},
+    async waitForProcessExitImpl() {
+      return true;
+    },
+    async runCliImpl(argv) {
+      cliCalls.push(argv);
+      return 0;
+    },
+  });
+
+  assert.deepEqual(cliCalls, [[
+    "start",
+    "--data-dir",
+    prodDir,
+    "--ws-url",
+    "wss://clawpool.dhf.pub/v1/agent-api/ws?agent_id=2035513096339984384",
+    "--agent-id",
+    "2035513096339984384",
+    "--api-key",
+    "ak_2035513096339984384_wyIkUkt9FyEZFJGHyvWHPu7ZOXkpj0KM",
+  ]]);
+});