@dhf-claude/grix 0.1.8

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "grix-claude-daemon",
+  "version": "0.1.0",
+  "description": "Claude Code channel plugin for Aibot Grix over the Agent API WebSocket.",
+  "author": {
+    "name": "Aibot"
+  },
+  "homepage": "https://grix.dhf.pub",
+  "repository": "https://github.com/askie/clawpool-claude",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "channel",
+    "grix",
+    "aibot"
+  ]
+}

package/README.md

@@ -0,0 +1,205 @@
+# @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.
+
+## Quick Start
+
+### 1. Install globally
+
+```bash
+npm install -g @dhf-claude/grix
+```
+
+### 2. Install the background service (first time)
+
+Get these 3 values from the Grix console first:
+
+- `wsUrl`
+- `agentId`
+- `apiKey`
+
+Then run:
+
+```bash
+grix-claude install --ws-url <ws_url> --agent-id <agent_id> --api-key <api_key>
+```
+
+This command will automatically:
+
+- Save connection settings
+- Install a user-level background service
+- Start the local `daemon` immediately
+- Let `daemon` handle session startup, resume, and message relay
+
+Supported background service managers:
+
+- macOS: `launchd`
+- Linux: `systemd --user`
+- Windows: Task Scheduler
+
+## Commands you will usually use
+
+```bash
+grix-claude status
+grix-claude restart
+grix-claude stop
+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
+
+## If you only want a temporary foreground run
+
+You can run without installing a background service:
+
+```bash
+grix-claude --ws-url <ws_url> --agent-id <agent_id> --api-key <api_key>
+```
+
+If config is already saved locally, you can also just run:
+
+```bash
+grix-claude
+```
+
+## How to start a Claude session
+
+Send this in the related Grix private chat:
+
+```text
+open <your_working_directory>
+```
+
+`daemon` will start or resume the matching Claude session for that directory.
+
+If you are already inside Claude, run:
+
+```text
+/grix:status
+```
+
+If the worker is attached to daemon, the link is healthy.
+
+## Common commands inside Claude
+
+| 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 |
+
+Connection parameters are now managed only through local CLI, not from inside Claude sessions.
+
+## Approvals and questions
+
+When Claude needs your confirmation or more information, messages are sent back to Grix.
+
+Interactive cards are used by default:
+
+- For approvals, click approve/reject on the card
+- For questions, fill the card and submit
+
+Text commands are still available as fallback:
+
+```text
+yes <request_id>
+no <request_id>
+/grix-question <request_id> your_answer
+```
+
+- Use manual text input only for debugging, troubleshooting, or when cards are unavailable
+
+## File sending
+
+Claude can send local files back to Grix. Maximum file size is 50MB, and only common image/video/document formats are supported.
+
+## Log troubleshooting
+
+Each AIBot session ID has an independent 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:
+
+- Worker process state changes and PID
+- Process relaunch after exit
+- Message delivery and result callbacks
+- Connectivity probes and timeout decisions
+
+Full troubleshooting steps:
+
+- `docs/session-log-troubleshooting.md`
+
+## CLI commands
+
+```text
+grix-claude install [options]
+grix-claude start [options]
+grix-claude stop [options]
+grix-claude restart [options]
+grix-claude status [options]
+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.
+
+## Common options
+
+```text
+--ws-url <value>      Grix Agent API WebSocket URL
+--agent-id <value>    Agent ID
+--api-key <value>     API Key
+--data-dir <path>     daemon data directory
+--chunk-limit <n>     max text chunk length
+--show-claude         show Claude in a visible Terminal window for debugging
+--no-launch           validate and save config only, do not start daemon
+--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
+- `--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.
+
+## Auto-build during development
+
+If you are changing code in this repository, run:
+
+```bash
+npm run dev
+```
+
+It continuously watches source changes and builds the latest artifacts to:
+
+- `dist/index.js`
+- `dist/daemon.js`
+
+For local integration testing, run this 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:
+
+```bash
+GRIX_CLAUDE_ENDPOINT='ws://127.0.0.1:27189/v1/agent-api/ws?agent_id=<agent_id>' \
+GRIX_CLAUDE_AGENT_ID='<agent_id>' \
+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.

package/bin/grix-claude.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../cli/main.js";
+
+await main();

package/cli/config.js

@@ -0,0 +1,136 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_OUTBOUND_TEXT_CHUNK_LIMIT } from "../server/config-store.js";
+import { readConnectionEnv } from "../server/connection-env.js";
+
+const serverName = "grix-claude";
+const configFileName = "grix-claude-config.json";
+
+function normalizeString(value) {
+  return String(value ?? "").trim();
+}
+
+function normalizePositiveInteger(value, fallbackValue) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric <= 0) {
+    return fallbackValue;
+  }
+  return Math.floor(numeric);
+}
+
+function resolveDefaultDataDir() {
+  return path.join(os.homedir(), ".claude", serverName);
+}
+
+export function resolvePackageRoot() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+export function resolvePackageBinPath() {
+  return path.join(resolvePackageRoot(), "bin", "grix-claude.js");
+}
+
+export function resolveServerEntryPath(packageRoot = resolvePackageRoot()) {
+  const sourceEntryPath = path.join(packageRoot, "server", "main.js");
+  if (existsSync(sourceEntryPath)) {
+    return sourceEntryPath;
+  }
+  const distEntryPath = path.join(packageRoot, "dist", "index.js");
+  if (existsSync(distEntryPath)) {
+    return distEntryPath;
+  }
+  throw new Error(`没有找到 grix-claude server 入口: ${packageRoot}`);
+}
+
+export function resolveDataDir(input) {
+  const explicitDir = normalizeString(input.dataDir);
+  if (explicitDir) {
+    return explicitDir;
+  }
+  const envDir = normalizeString(input.env?.CLAUDE_PLUGIN_DATA || input.env?.GRIX_CLAUDE_DATA_DIR);
+  if (envDir) {
+    return envDir;
+  }
+  return resolveDefaultDataDir();
+}
+
+export function resolveConfigPath(dataDir) {
+  return path.join(dataDir, configFileName);
+}
+
+async function readStoredConfig(filePath) {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch (error) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "code" in error &&
+      error.code === "ENOENT"
+    ) {
+      return {};
+    }
+    if (error instanceof SyntaxError) {
+      return {};
+    }
+    throw error;
+  }
+}
+
+export async function loadConfig({ dataDir, env = process.env, args = {} }) {
+  const configPath = resolveConfigPath(dataDir);
+  const stored = await readStoredConfig(configPath);
+  const connectionEnv = readConnectionEnv(env);
+  return {
+    schema_version: 1,
+    ws_url: normalizeString(connectionEnv.ws_url || args.wsUrl || stored.ws_url),
+    agent_id: normalizeString(connectionEnv.agent_id || args.agentId || stored.agent_id),
+    api_key: normalizeString(connectionEnv.api_key || args.apiKey || stored.api_key),
+    outbound_text_chunk_limit: normalizePositiveInteger(
+      connectionEnv.outbound_text_chunk_limit
+      || args.chunkLimit
+      || stored.outbound_text_chunk_limit,
+      DEFAULT_OUTBOUND_TEXT_CHUNK_LIMIT,
+    ),
+  };
+}
+
+export function validateConfig(config) {
+  if (!config.ws_url) {
+    throw new Error("缺少 ws 地址，请传 --ws-url。");
+  }
+  if (!/^wss?:\/\//i.test(config.ws_url)) {
+    throw new Error("ws 地址必须以 ws:// 或 wss:// 开头。");
+  }
+  if (!config.agent_id) {
+    throw new Error("缺少 agent ID，请传 --agent-id。");
+  }
+  if (!config.api_key) {
+    throw new Error("缺少 API Key，请传 --api-key。");
+  }
+}
+
+export async function writeConfig({ dataDir, config }) {
+  await mkdir(dataDir, { recursive: true, mode: 0o700 });
+  const configPath = resolveConfigPath(dataDir);
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  return configPath;
+}
+
+export function maskApiKey(apiKey) {
+  const normalized = normalizeString(apiKey);
+  if (!normalized) {
+    return "";
+  }
+  if (normalized.length <= 8) {
+    return `${normalized.slice(0, 2)}***`;
+  }
+  return `${normalized.slice(0, 4)}***${normalized.slice(-2)}`;
+}

package/cli/config.test.js

@@ -0,0 +1,63 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { loadConfig, resolveDataDir, resolveServerEntryPath } from "./config.js";
+
+test("resolveDataDir prefers explicit input over environment", () => {
+  assert.equal(
+    resolveDataDir({
+      dataDir: "/tmp/custom-data",
+      env: {
+        CLAUDE_PLUGIN_DATA: "/tmp/env-data",
+      },
+    }),
+    "/tmp/custom-data",
+  );
+});
+
+test("loadConfig merges stored values with cli input and environment", async () => {
+  const tempDir = path.join(process.cwd(), "tmp-config-test");
+  const config = await loadConfig({
+    dataDir: tempDir,
+    env: {
+      GRIX_CLAUDE_ENDPOINT: "ws://env.example/ws",
+      GRIX_CLAUDE_API_KEY: "env-key",
+    },
+    args: {
+      wsUrl: "wss://example.com/ws",
+      agentId: "agent-1",
+      chunkLimit: "2048",
+    },
+  });
+
+  assert.deepEqual(config, {
+    schema_version: 1,
+    ws_url: "ws://env.example/ws",
+    agent_id: "agent-1",
+    api_key: "env-key",
+    outbound_text_chunk_limit: 2048,
+  });
+});
+
+test("resolveServerEntryPath prefers source entry when source and dist both exist", async () => {
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "grix-config-source-entry-"));
+  const sourceDir = path.join(tempDir, "server");
+  const distDir = path.join(tempDir, "dist");
+  await mkdir(sourceDir, { recursive: true });
+  await mkdir(distDir, { recursive: true });
+  await writeFile(path.join(sourceDir, "main.js"), "export default 1;\n", "utf8");
+  await writeFile(path.join(distDir, "index.js"), "export default 2;\n", "utf8");
+
+  assert.equal(resolveServerEntryPath(tempDir), path.join(sourceDir, "main.js"));
+});
+
+test("resolveServerEntryPath falls back to dist entry when source is missing", async () => {
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "grix-config-dist-entry-"));
+  const distDir = path.join(tempDir, "dist");
+  await mkdir(distDir, { recursive: true });
+  await writeFile(path.join(distDir, "index.js"), "export default 2;\n", "utf8");
+
+  assert.equal(resolveServerEntryPath(tempDir), path.join(distDir, "index.js"));
+});