@clastres/groundcontrol 0.1.6 → 0.1.8

package/hook.mjs

@@ -0,0 +1,109 @@
+// Ground Control PermissionRequest hook — runs inside Claude Code, not the daemon.
+//
+// Claude Code invokes this whenever a tool call needs a permission decision. It
+// hands the request to the local daemon over a unix socket; the daemon decides
+// whether to hold it for the phone or let it fall straight through.
+//
+// The one rule that matters here: when anything at all goes wrong (no daemon,
+// no answer, malformed reply, broken pipe) this exits 0 printing nothing, which
+// Claude Code reads as "no decision" and shows its normal terminal prompt. A
+// user who has never opened the app must not be able to tell this is installed.
+
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+const SOCKET = path.join(os.homedir(), '.groundcontrol', 'approvals.sock');
+// Backstop only. The daemon settles every request itself, either with a
+// decision or with an explicit pass, so reaching this means the daemon wedged.
+const HARD_CAP_MS = 12 * 60 * 60 * 1000;
+const STDIN_MS = 5000;
+
+/// Exit without a decision. Claude Code prompts in the terminal as usual.
+function pass() {
+  process.exit(0);
+}
+
+function decide(decision) {
+  // An unrecognised behaviour would be a silent deny in some Claude versions,
+  // so anything that is not a clean allow/deny falls back to the prompt.
+  if (!decision || (decision.behavior !== 'allow' && decision.behavior !== 'deny')) pass();
+  const out = JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'PermissionRequest', decision },
+  });
+  // writeSync, not process.stdout.write: stdout is a pipe here, so an async
+  // write followed by process.exit can truncate. Half a JSON object would be
+  // unparseable, which is safe (Claude prompts) but silently loses the answer.
+  try { fs.writeSync(1, out); } catch { /* nothing left to do but pass */ }
+  process.exit(0);
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let buf = '';
+    const done = (v) => { clearTimeout(timer); resolve(v); };
+    const timer = setTimeout(() => done(buf), STDIN_MS);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (d) => { buf += d; });
+    process.stdin.on('end', () => done(buf));
+    process.stdin.on('error', () => done(''));
+  });
+}
+
+const raw = await readStdin();
+let payload;
+try { payload = JSON.parse(raw); } catch { pass(); }
+if (!payload || typeof payload !== 'object') pass();
+
+// Only session_id is genuinely required: it is what ties the request to a
+// session on the island. Claude Code 2.1.220 sends no tool_use_id on this
+// event (verified against a live session), and the daemon mints its own
+// request id anyway, so requiring one here would drop every real request.
+if (!payload.session_id) pass();
+
+const sock = net.connect(SOCKET);
+sock.setEncoding('utf8');
+
+let settled = false;
+const finish = (fn, arg) => {
+  if (settled) return;
+  settled = true;
+  try { sock.destroy(); } catch {}
+  fn(arg);
+};
+
+const cap = setTimeout(() => finish(pass), HARD_CAP_MS);
+cap.unref?.();
+
+// No daemon, stale socket file, wrong permissions: all of these land here and
+// all of them mean "behave exactly like Ground Control is not installed".
+sock.on('error', () => finish(pass));
+// A close before any reply means the daemon died mid-decision.
+sock.on('close', () => finish(pass));
+
+sock.on('connect', () => {
+  sock.write(JSON.stringify({
+    v: 1,
+    sessionId: payload.session_id,
+    toolUseId: payload.tool_use_id || '',
+    toolName: payload.tool_name || 'tool',
+    toolInput: payload.tool_input || {},
+    cwd: payload.cwd || '',
+    permissionMode: payload.permission_mode || '',
+    permissionContext: payload.permission_context || null,
+  }) + '\n');
+});
+
+let inbox = '';
+sock.on('data', (chunk) => {
+  inbox += chunk;
+  const nl = inbox.indexOf('\n');
+  if (nl === -1) return;
+  let reply;
+  try { reply = JSON.parse(inbox.slice(0, nl)); } catch { return finish(pass); }
+  // decision null is the daemon explicitly passing (you are at the Mac, the
+  // hold expired, or the phone never answered).
+  if (!reply || !reply.decision) return finish(pass);
+  finish(decide, reply.decision);
+});

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@clastres/groundcontrol",
-  "version": "0.1.6",
-  "description": "See and command your Claude Code sessions from your iPhone. Pairs the Ground Control app with the agents running on this Mac, end to end encrypted.",
+  "version": "0.1.8",
+  "description": "See and command your coding agents from your iPhone. Pairs the Ground Control app with Claude Code, Codex, Kimi and Grok Bot sessions running on this Mac, end to end encrypted.",
   "bin": {
     "groundcontrol": "bin/groundcontrol.mjs"
   },
+  "scripts": {
+    "test": "node test/run.mjs"
+  },
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -16,6 +19,9 @@
   "keywords": [
     "claude",
     "claude-code",
+    "codex",
+    "kimi",
+    "grok",
     "ai",
     "agents",
     "cli",

package/test/binaries.mjs

@@ -0,0 +1,68 @@
+// Agent binaries are looked up on use, not at daemon startup.
+//
+// This is a regression test for a real failure: the daemon had been running
+// since Aug 4, Kimi Code was installed on Aug 12, and because the binary
+// consts were resolved once at boot the session showed up on the phone,
+// streamed its transcript, and refused every prompt with "binary not found"
+// for eight days. Session discovery rescans the disk constantly; binary
+// lookup did not.
+//
+// The resolver block is extracted from daemon.mjs rather than copied, with an
+// injected clock so the one minute memo can be stepped over instantly.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAEMON = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'daemon.mjs');
+const src = fs.readFileSync(DAEMON, 'utf8');
+const start = src.indexOf('// Every agent binary is resolved on use');
+const end = src.indexOf('// ---------- Claude Code session discovery ----------');
+if (start < 0 || end < 0 || end < start) throw new Error('could not locate the binary resolver block in daemon.mjs');
+const block = src.slice(start, end);
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gc-bin-'));
+const home = path.join(tmp, 'home');
+fs.mkdirSync(path.join(home, '.kimi-code', 'bin'), { recursive: true });
+const kimiPath = path.join(home, '.kimi-code', 'bin', 'kimi');
+
+let now = 1_000_000;
+const clock = { now: () => now };
+const fakeOs = { ...os, homedir: () => home };
+const executable = (p) => { try { fs.accessSync(p, fs.constants.X_OK); return p; } catch { return null; } };
+const which = () => null;           // nothing on PATH, which is the real case here
+const quiet = { log: () => {} };    // swallow the startup banner
+
+const load = () => new Function('fs', 'os', 'path', 'Date', 'which', 'executable', 'console',
+  `${block}\n return { kimiCodeBin, claudeBin, codexBin, resolveBin };`)(
+  fs, fakeOs, path, clock, which, executable, quiet);
+
+const { kimiCodeBin } = load();
+
+let failures = 0;
+const check = (label, cond) => { console.log(`${cond ? 'ok  ' : 'FAIL'} ${label}`); if (!cond) failures++; };
+
+// Boot: ~/.kimi-code exists but the binary is not installed yet.
+check('not installed yet reads as missing', kimiCodeBin() === null);
+
+// Kimi Code installs while the daemon keeps running. This is the exact case
+// that left a session readable but unanswerable.
+fs.writeFileSync(kimiPath, '#!/bin/sh\n');
+fs.chmodSync(kimiPath, 0o755);
+
+check('still cached inside the memo window', kimiCodeBin() === null);
+now += 61_000;
+check('picked up a minute after install', kimiCodeBin() === kimiPath);
+
+// And the reverse: an uninstall is noticed rather than cached forever.
+fs.rmSync(kimiPath);
+now += 61_000;
+check('uninstall clears back to missing', kimiCodeBin() === null);
+
+// A lookup that throws must not take a prompt down with it.
+const { resolveBin } = load();
+check('a throwing lookup returns null', resolveBin('boom', () => { throw new Error('nope'); }) === null);
+
+fs.rmSync(tmp, { recursive: true, force: true });
+console.log(failures ? `\n${failures} FAILURE(S)` : '\nall checks passed');
+process.exit(failures ? 1 : 0);

package/test/grokbot.mjs

@@ -0,0 +1,86 @@
+// Runs the real Grok Bot reader out of daemon.mjs against whatever replica this
+// Mac has. The block is extracted from source rather than copied, so the test
+// cannot drift from what the daemon ships.
+//
+// The daemon is one long script that connects to the relay on import, so there
+// is nothing to import: pulling the section out by its comment markers and
+// evaluating it with its handful of helpers injected is what keeps this honest.
+//
+// On a Mac without Grok Bot installed the roster assertions are skipped and the
+// machine independent ones still run.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAEMON = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'daemon.mjs');
+const src = fs.readFileSync(DAEMON, 'utf8');
+const start = src.indexOf('// ---------- Grok Bot session discovery ----------');
+const end = src.indexOf('/// The phone-facing shape of a held request.');
+if (start < 0 || end < 0 || end < start) throw new Error('could not locate the Grok Bot block in daemon.mjs');
+const block = src.slice(start, end);
+
+const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
+const isoOf = (t) => { try { return t ? new Date(t).toISOString() : null; } catch { return null; } };
+const memoScan = (_key, _file, fn) => fn();
+const transcriptCache = new Map();
+
+const load = (source, cache) => new Function('fs', 'os', 'path', 'readJson', 'isoOf', 'memoScan', 'transcriptCache',
+  `${source}\n return { readGrokBotSessions, readGrokBotMessages, b32decode, GROKBOT_DIR };`)(
+  fs, os, path, readJson, isoOf, memoScan, cache);
+
+const { readGrokBotSessions, readGrokBotMessages, b32decode, GROKBOT_DIR } = load(block, transcriptCache);
+
+let failures = 0;
+const check = (label, cond, detail = '') => {
+  console.log(`${cond ? 'ok  ' : 'FAIL'} ${label}${detail ? `  ${detail}` : ''}`);
+  if (!cond) failures++;
+};
+
+// A store key the app really writes, so a change to the encoding is caught here
+// rather than by an empty island.
+const known = 'onqw4zbomnwgszlooqxhg3djmnss4y3mnfsw45bnnvsxiyjomfrwg33vnz2c243mn52a';
+check('b32decode reads a real store key', b32decode(known) === 'sand.client.slice.client-meta.account-slot', b32decode(known));
+check('b32decode rejects junk', b32decode('!!!!') === '');
+
+// A Mac without Grok Bot must return an empty list rather than throw.
+check('missing install returns empty, does not throw',
+  load(block.replace(/const GROKBOT_DIR = .*/, "const GROKBOT_DIR = '/nope/not/here';"), new Map())
+    .readGrokBotSessions().length === 0);
+
+const sessions = fs.existsSync(GROKBOT_DIR) ? readGrokBotSessions() : [];
+if (!sessions.length) {
+  console.log(`\nskipped the roster checks: no Bots found in ${GROKBOT_DIR}`);
+  console.log(failures ? `\n${failures} FAILURE(S)` : '\nall checks passed');
+  process.exit(failures ? 1 : 0);
+}
+
+console.log(`\n${sessions.length} bot(s) found\n`);
+for (const s of sessions) {
+  check(`${s.name}: id is a uuid`, /^[0-9a-f-]{36}$/.test(s.id));
+  check(`${s.name}: status is one the app understands`, ['idle', 'busy', 'waiting'].includes(s.status));
+  check(`${s.name}: has a name`, !!s.name);
+  check(`${s.name}: startedAt set`, s.startedAt > 0);
+  check(`${s.name}: updatedAt set`, s.updatedAt > 0);
+  check(`${s.name}: read only flagged`, s.readOnly === true);
+  // Every field the Swift Session struct decodes as non-optional must be here,
+  // or the phone drops the whole snapshot, not just this row.
+  for (const k of ['id', 'name', 'cwd', 'project', 'status', 'updatedAt', 'startedAt']) {
+    check(`${s.name}: ${k} present for Swift decode`, s[k] !== undefined && s[k] !== null);
+  }
+
+  const file = transcriptCache.get(s.id);
+  check(`${s.name}: transcript located`, !!file);
+  if (!file) continue;
+  const msgs = readGrokBotMessages(file);
+  check(`${s.name}: transcript has messages`, msgs.length > 0);
+  check(`${s.name}: roles are user/assistant only`, msgs.every((m) => m.role === 'user' || m.role === 'assistant'));
+  check(`${s.name}: every message has a timestamp`, msgs.every((m) => !!m.ts));
+  check(`${s.name}: lastMessage matches transcript tail`, s.lastMessage?.text === msgs[msgs.length - 1]?.text);
+  // The app stores a ProseMirror doc beside every typed turn. Leaking it into
+  // the transcript would put raw JSON on the phone.
+  check(`${s.name}: no raw richText leaked into text`, msgs.every((m) => !m.text.includes('"type":"doc"')));
+}
+
+console.log(failures ? `\n${failures} FAILURE(S)` : '\nall checks passed');
+process.exit(failures ? 1 : 0);

package/test/run.mjs

@@ -0,0 +1,23 @@
+// Every test in this directory, in one run. Plain node, no framework, matching
+// the rest of the CLI: the daemon ships with two runtime dependencies and a
+// test runner is not going to be the third.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const dir = path.dirname(fileURLToPath(import.meta.url));
+const files = fs.readdirSync(dir).filter((f) => f.endsWith('.mjs') && f !== 'run.mjs').sort();
+
+let failed = 0;
+for (const f of files) {
+  console.log(`\n=== ${f} ===`);
+  try {
+    execFileSync(process.execPath, [path.join(dir, f)], { stdio: 'inherit' });
+  } catch {
+    failed++;
+  }
+}
+
+console.log(failed ? `\n${failed} of ${files.length} test file(s) failed` : `\n${files.length} test file(s) passed`);
+process.exit(failed ? 1 : 0);