clawmini 0.0.8 → 0.0.9

package/src/cli/supervisor-actions.ts

@@ -0,0 +1,267 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+import { detectInstall } from './install-detection.js';
+import {
+  startControlServer,
+  type ControlRequest,
+  type ControlResponse,
+} from './supervisor-control.js';
+import { removeSupervisorPid } from './supervisor-pid.js';
+import { enqueuePendingReply, dequeuePendingReply } from '../daemon/pending-replies.js';
+import type { Supervisor } from './supervisor.js';
+
+// Grace period before a destructive action fires. The daemon-side router
+// awaits sendControlRequest but the daemon still needs to flush the user
+// message + ack reply through the chat log before the daemon process is
+// killed. SIGTERM arriving mid-flush is non-fatal (the daemon's own SIGTERM
+// handler still runs) but the grace makes the ordering deterministic.
+const ACTION_GRACE_MS = 1000;
+
+/**
+ * Wire up the supervisor control socket so the daemon can request
+ * /restart, /shutdown, and /upgrade out-of-band.
+ */
+export function startSupervisorControl(supervisor: Supervisor): void {
+  startControlServer({
+    restart: async (req: ControlRequest): Promise<ControlResponse> => {
+      // Enqueue BEFORE scheduling the kill, so a crash between enqueue and
+      // kill leaves the post-restart message ready to drain.
+      if (req.chatId) {
+        enqueuePendingReply({
+          chatId: req.chatId,
+          kind: 'restart-complete',
+          ...(req.messageId ? { messageId: req.messageId } : {}),
+        });
+      }
+      setTimeout(() => {
+        // restartAll instead of restartService('daemon'): adapters hold
+        // tRPC subscriptions to the daemon and won't reconnect on their
+        // own when the daemon process dies, so outbound replies wouldn't
+        // make it back to the chat. Bouncing the adapters forces them to
+        // re-subscribe to the new daemon.
+        void supervisor.restartAll().catch((err) => {
+          process.stderr.write(
+            `[supervisor] /restart failed: ${err instanceof Error ? err.message : String(err)}\n`
+          );
+          // Restart failed — back out the queued reply so the next successful
+          // start doesn't surface a phantom "restarted" message.
+          if (req.chatId && req.messageId) {
+            dequeuePendingReply(
+              (e) => e.kind === 'restart-complete' && e.messageId === req.messageId
+            );
+          }
+        });
+      }, ACTION_GRACE_MS);
+      return { ok: true };
+    },
+    shutdown: async (): Promise<ControlResponse> => {
+      setTimeout(() => void supervisor.shutdown(0), ACTION_GRACE_MS);
+      return { ok: true };
+    },
+    upgrade: async (req: ControlRequest): Promise<ControlResponse> => {
+      const info = detectInstall();
+      if (!info.isNpmGlobal) {
+        return {
+          ok: false,
+          error: `not installed via npm install -g (running from ${info.entryRealPath})`,
+        };
+      }
+      const version = req.version?.trim();
+      if (!version) {
+        return { ok: false, error: 'missing target version' };
+      }
+      if (!isAcceptableVersion(version)) {
+        return { ok: false, error: `invalid version: ${version}` };
+      }
+      setTimeout(() => {
+        void runUpgrade(supervisor, version, req.chatId, req.messageId).catch((err) => {
+          process.stderr.write(
+            `[supervisor] /upgrade encountered an unexpected error: ${err instanceof Error ? err.message : String(err)}\n`
+          );
+        });
+      }, ACTION_GRACE_MS);
+      return { ok: true };
+    },
+  });
+}
+
+// Accept semver-ish versions (1.2.3, 1.2.3-beta.1, etc.), the literal
+// "latest", or a dist-tag (alphanumeric + dashes). Reject anything else so a
+// malicious client can't smuggle shell metacharacters or `--registry=...`
+// into the npm command line.
+export function isAcceptableVersion(version: string): boolean {
+  return /^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,63}$/.test(version);
+}
+
+/**
+ * In-place upgrade. Order:
+ *   1. `npm install -g clawmini@<version>` (services kept running so the
+ *      user isn't left in the dark if the install fails).
+ *   2. Resolve the freshly-installed binary by absolute path. Bail out with
+ *      an upgrade-failed reply if it's missing.
+ *   3. Enqueue the upgrade-complete reply.
+ *   4. Stop all children, spawn the replacement supervisor, exit.
+ *
+ * Any failure path enqueues an upgrade-failed reply (so the user gets visible
+ * feedback) and restarts the daemon to drain it, rather than silently exiting.
+ */
+export async function runUpgrade(
+  supervisor: Supervisor,
+  version: string,
+  chatId?: string,
+  messageId?: string
+): Promise<void> {
+  const info = detectInstall();
+  if (!info.isNpmGlobal || !info.npmRootRealPath) {
+    process.stderr.write(
+      `[supervisor] /upgrade aborted: clawmini is not installed via npm install -g (running from ${info.entryRealPath}).\n`
+    );
+    return;
+  }
+
+  const installErr = await runNpmInstall(version);
+  if (installErr) {
+    process.stderr.write(`[supervisor] /upgrade failed: ${installErr}\n`);
+    if (chatId) {
+      enqueuePendingReply({
+        chatId,
+        kind: 'upgrade-failed',
+        ...(messageId ? { messageId } : {}),
+        requestedVersion: version,
+        reason: installErr,
+      });
+      // The daemon is still running (we never stopped it). Bounce the whole
+      // stack so the new daemon drains the failure message AND adapters
+      // re-subscribe to it.
+      await supervisor.restartAll().catch((err) => {
+        process.stderr.write(
+          `[supervisor] additionally failed to restart services to surface the failure: ${err instanceof Error ? err.message : String(err)}\n`
+        );
+      });
+    }
+    return;
+  }
+
+  // npm install reported success — confirm the binary exists where we expect
+  // before we start tearing down services.
+  const newCli = path.join(info.npmRootRealPath, 'clawmini', 'dist', 'cli', 'index.mjs');
+  if (!fs.existsSync(newCli)) {
+    const reason = `npm install reported success but ${newCli} is missing`;
+    process.stderr.write(`[supervisor] /upgrade aborted: ${reason}\n`);
+    if (chatId) {
+      enqueuePendingReply({
+        chatId,
+        kind: 'upgrade-failed',
+        ...(messageId ? { messageId } : {}),
+        requestedVersion: version,
+        reason,
+      });
+      await supervisor.restartAll().catch(() => {});
+    }
+    return;
+  }
+
+  if (chatId) {
+    enqueuePendingReply({
+      chatId,
+      kind: 'upgrade-complete',
+      ...(messageId ? { messageId } : {}),
+      requestedVersion: version,
+    });
+  }
+
+  process.stderr.write('[supervisor] /upgrade: stopping all services...\n');
+  await supervisor.stopAllChildren();
+
+  process.stderr.write(`[supervisor] /upgrade: relaunching ${newCli} serve --detach...\n`);
+  // Drop our pid file so the new supervisor doesn't see us as already
+  // running; it will write its own pid on startup.
+  removeSupervisorPid();
+
+  // Run the new entry point directly via the current Node binary so the
+  // spawn doesn't depend on the shell's PATH being refreshed (which it isn't
+  // for an already-running process).
+  const replacement = spawn(process.execPath, [newCli, 'serve', '--detach'], {
+    detached: true,
+    stdio: 'ignore',
+    cwd: process.cwd(),
+    env: process.env,
+  });
+
+  const spawnOk = await waitForSpawn(replacement);
+  if (!spawnOk) {
+    process.stderr.write(
+      `[supervisor] /upgrade: replacement supervisor failed to spawn — restarting in place\n`
+    );
+    if (chatId) {
+      // Roll back the optimistic complete reply and replace it with a
+      // failure entry so the user knows the upgrade landed on disk but
+      // never came back up.
+      dequeuePendingReply(
+        (e) =>
+          e.kind === 'upgrade-complete' &&
+          e.messageId === messageId &&
+          e.requestedVersion === version
+      );
+      enqueuePendingReply({
+        chatId,
+        kind: 'upgrade-failed',
+        ...(messageId ? { messageId } : {}),
+        requestedVersion: version,
+        reason: 'replacement supervisor failed to spawn',
+      });
+    }
+    // Bring the whole stack back (daemon + adapters + web) so the failure
+    // message is drained AND adapters can deliver it to the chat.
+    try {
+      await supervisor.restartAll();
+    } catch (err) {
+      process.stderr.write(
+        `[supervisor] additionally failed to restart services after spawn failure: ${err instanceof Error ? err.message : String(err)}\n`
+      );
+    }
+    return;
+  }
+
+  replacement.unref();
+  process.exit(0);
+}
+
+function runNpmInstall(version: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    // execFile-style argv (no shell), so the version argument can't be
+    // interpreted by a shell even if it slipped past isAcceptableVersion.
+    const child = spawn('npm', ['install', '-g', `clawmini@${version}`], {
+      stdio: 'inherit',
+      env: process.env,
+    });
+    child.on('exit', (code) => {
+      if (code === 0) resolve(null);
+      else resolve(`npm install -g exited with code ${code}`);
+    });
+    child.on('error', (err) => {
+      resolve(err instanceof Error ? err.message : String(err));
+    });
+  });
+}
+
+function waitForSpawn(child: ReturnType<typeof spawn>, timeoutMs = 5000): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (ok: boolean): void => {
+      if (settled) return;
+      settled = true;
+      resolve(ok);
+    };
+    child.once('spawn', () => settle(true));
+    child.once('error', (err) => {
+      process.stderr.write(`[supervisor] replacement spawn error: ${err.message}\n`);
+      settle(false);
+    });
+    // 'spawn' fires almost immediately on success. Cap the wait so we never
+    // hang if neither event fires.
+    setTimeout(() => settle(true), timeoutMs);
+  });
+}

package/src/cli/supervisor-control.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  startControlServer,
+  sendControlRequest,
+  type ControlAction,
+  type ControlHandler,
+  type ControlRequest,
+} from './supervisor-control.js';
+
+describe('supervisor control socket', () => {
+  const cleanup: Array<() => void> = [];
+
+  afterEach(() => {
+    while (cleanup.length) {
+      try {
+        cleanup.pop()!();
+      } catch {
+        // best-effort
+      }
+    }
+  });
+
+  function makeSocketPath(): string {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'clawmini-ctl-'));
+    cleanup.push(() => fs.rmSync(tmp, { recursive: true, force: true }));
+    return path.join(tmp, 'supervisor.sock');
+  }
+
+  it('round-trips a request to the matching handler and forwards extra fields', async () => {
+    const sockPath = makeSocketPath();
+    const seen: ControlRequest[] = [];
+    const handlers: Record<ControlAction, ControlHandler> = {
+      restart: async (req) => {
+        seen.push(req);
+        return { ok: true };
+      },
+      shutdown: async () => ({ ok: true }),
+      upgrade: async () => ({ ok: true }),
+    };
+    const server = startControlServer(handlers, sockPath);
+    cleanup.push(() => server.close());
+
+    const res = await sendControlRequest(
+      { action: 'restart', chatId: 'c1', messageId: 'm1' },
+      sockPath
+    );
+    expect(res).toEqual({ ok: true });
+    expect(seen).toEqual([{ action: 'restart', chatId: 'c1', messageId: 'm1' }]);
+  });
+
+  it('returns the handler error when the handler rejects', async () => {
+    const sockPath = makeSocketPath();
+    const server = startControlServer(
+      {
+        restart: async () => {
+          throw new Error('boom');
+        },
+        shutdown: async () => ({ ok: true }),
+        upgrade: async () => ({ ok: true }),
+      },
+      sockPath
+    );
+    cleanup.push(() => server.close());
+
+    const res = await sendControlRequest({ action: 'restart' }, sockPath);
+    expect(res.ok).toBe(false);
+    expect(res.error).toBe('boom');
+  });
+
+  it('rejects unknown actions', async () => {
+    const sockPath = makeSocketPath();
+    const server = startControlServer(
+      {
+        restart: async () => ({ ok: true }),
+        shutdown: async () => ({ ok: true }),
+        upgrade: async () => ({ ok: true }),
+      },
+      sockPath
+    );
+    cleanup.push(() => server.close());
+
+    const res = await sendControlRequest({ action: 'unknown' as ControlAction }, sockPath);
+    expect(res.ok).toBe(false);
+    expect(res.error).toContain('unknown action');
+  });
+
+  it('overwrites a stale socket file at startup', async () => {
+    const sockPath = makeSocketPath();
+    fs.writeFileSync(sockPath, ''); // pretend a stale file is left over
+    const server = startControlServer(
+      {
+        restart: async () => ({ ok: true }),
+        shutdown: async () => ({ ok: true }),
+        upgrade: async () => ({ ok: true }),
+      },
+      sockPath
+    );
+    cleanup.push(() => server.close());
+
+    const res = await sendControlRequest({ action: 'shutdown' }, sockPath);
+    expect(res).toEqual({ ok: true });
+  });
+
+  it('chmods the socket to 0600 so other users on the host cannot connect', async () => {
+    const sockPath = makeSocketPath();
+    const server = startControlServer(
+      {
+        restart: async () => ({ ok: true }),
+        shutdown: async () => ({ ok: true }),
+        upgrade: async () => ({ ok: true }),
+      },
+      sockPath
+    );
+    cleanup.push(() => server.close());
+
+    // Round-trip a request to make sure the server is fully up — once we get
+    // a response, the listen() callback that does the chmod has fired.
+    const res = await sendControlRequest({ action: 'restart' }, sockPath);
+    expect(res.ok).toBe(true);
+
+    const stat = fs.statSync(sockPath);
+    // Compare mode bits, not the full mode (which includes the file type).
+    expect(stat.mode & 0o777).toBe(0o600);
+  });
+});

package/src/cli/supervisor-control.ts

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+
+import { getClawminiDir } from '../shared/workspace.js';
+
+export type ControlAction = 'restart' | 'shutdown' | 'upgrade';
+
+export interface ControlRequest {
+  action: ControlAction;
+  /** Target version for `upgrade` (e.g. "1.2.3" or "latest"). */
+  version?: string;
+  /** Chat to deliver the post-action SystemMessage to. */
+  chatId?: string;
+  /** User message that triggered the action, threaded onto the reply. */
+  messageId?: string;
+}
+
+export interface ControlResponse {
+  ok: boolean;
+  error?: string;
+}
+
+// Kept short on purpose: AF_UNIX sun_path is 104 bytes on macOS, 108 on
+// Linux. A workspace nested a few directories deep + ".clawmini/super.sock"
+// is already close to the limit; "supervisor.sock" pushed common paths over
+// it (EINVAL from listen()).
+export function getControlSocketPath(startDir = process.cwd()): string {
+  return path.join(getClawminiDir(startDir), 'super.sock');
+}
+
+export type ControlHandler = (req: ControlRequest) => Promise<ControlResponse> | ControlResponse;
+
+export function startControlServer(
+  handlers: Record<ControlAction, ControlHandler>,
+  socketPath = getControlSocketPath()
+): net.Server {
+  if (fs.existsSync(socketPath)) {
+    try {
+      fs.unlinkSync(socketPath);
+    } catch {
+      // best-effort
+    }
+  }
+
+  const server = net.createServer((socket) => {
+    let buf = '';
+    let handled = false;
+
+    const respond = (res: ControlResponse): void => {
+      if (handled) return;
+      handled = true;
+      socket.end(JSON.stringify(res) + '\n');
+    };
+
+    socket.on('data', (chunk) => {
+      if (handled) return;
+      buf += chunk.toString();
+      const idx = buf.indexOf('\n');
+      if (idx === -1) return;
+      const line = buf.slice(0, idx);
+      let req: ControlRequest;
+      try {
+        req = JSON.parse(line) as ControlRequest;
+      } catch {
+        respond({ ok: false, error: 'invalid request' });
+        return;
+      }
+      const handler = handlers[req.action];
+      if (!handler) {
+        respond({ ok: false, error: `unknown action: ${req.action}` });
+        return;
+      }
+      Promise.resolve()
+        .then(() => handler(req))
+        .then(
+          (res) => respond(res),
+          (err: unknown) =>
+            respond({ ok: false, error: err instanceof Error ? err.message : String(err) })
+        );
+    });
+
+    socket.on('error', () => {
+      // Ignore; the client likely went away mid-write.
+    });
+  });
+
+  server.listen(socketPath, () => {
+    // Restrict to the owning user. The control channel can shut down or
+    // upgrade clawmini, so a process running as another local user must not
+    // be able to connect just because they can reach the .clawmini directory.
+    try {
+      fs.chmodSync(socketPath, 0o600);
+    } catch {
+      // best-effort
+    }
+  });
+  return server;
+}
+
+export function sendControlRequest(
+  req: ControlRequest,
+  socketPath = getControlSocketPath(),
+  timeoutMs = 5000
+): Promise<ControlResponse> {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection({ path: socketPath });
+    let buf = '';
+    let settled = false;
+
+    const finish = (fn: () => void): void => {
+      if (settled) return;
+      settled = true;
+      try {
+        socket.destroy();
+      } catch {
+        // best-effort
+      }
+      fn();
+    };
+
+    const timer = setTimeout(() => {
+      finish(() => reject(new Error(`Control request timed out after ${timeoutMs}ms`)));
+    }, timeoutMs);
+
+    socket.on('connect', () => {
+      socket.write(JSON.stringify(req) + '\n');
+    });
+    socket.on('data', (chunk) => {
+      buf += chunk.toString();
+      const idx = buf.indexOf('\n');
+      if (idx !== -1) {
+        const line = buf.slice(0, idx);
+        clearTimeout(timer);
+        try {
+          const res = JSON.parse(line) as ControlResponse;
+          finish(() => resolve(res));
+        } catch (err) {
+          finish(() => reject(err instanceof Error ? err : new Error(String(err))));
+        }
+      }
+    });
+    socket.on('error', (err) => {
+      clearTimeout(timer);
+      finish(() => reject(err));
+    });
+    socket.on('end', () => {
+      // If the server closed before sending us a full line, surface it.
+      if (!settled) {
+        clearTimeout(timer);
+        finish(() => reject(new Error('Control server closed connection without responding')));
+      }
+    });
+  });
+}

package/src/cli/supervisor-pid.ts

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { getClawminiDir } from '../shared/workspace.js';
+
+export function getSupervisorPidPath(startDir = process.cwd()): string {
+  return path.join(getClawminiDir(startDir), 'supervisor.pid');
+}
+
+// Returns the kernel-reported start time of `pid` as an opaque string, or
+// null if the process doesn't exist. The exact format is platform-defined
+// but stable per-host, which is all we need: we only ever compare the
+// stored value against a fresh read on the same machine.
+function getProcessStartTime(pid: number): string | null {
+  try {
+    const out = execFileSync('ps', ['-p', String(pid), '-o', 'lstart='], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const trimmed = out.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  } catch {
+    return null;
+  }
+}
+
+// The pid file stores `<pid>:<start-time>` so we can detect pid reuse:
+// `kill(pid, 0)` only confirms *something* with that pid is alive. After
+// the supervisor exits the OS may hand the same pid to an unrelated
+// process (browser tab, ssh, etc.) — without the start-time check we'd
+// happily SIGTERM that.
+export function readSupervisorPid(startDir = process.cwd()): number | null {
+  const p = getSupervisorPidPath(startDir);
+  if (!fs.existsSync(p)) return null;
+  const content = fs.readFileSync(p, 'utf-8').trim();
+  const sep = content.indexOf(':');
+  if (sep <= 0) return null;
+  const pid = parseInt(content.slice(0, sep), 10);
+  const storedStart = content.slice(sep + 1).trim();
+  if (!Number.isFinite(pid) || pid <= 0 || storedStart.length === 0) return null;
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return null;
+  }
+  const currentStart = getProcessStartTime(pid);
+  if (currentStart === null || currentStart !== storedStart) return null;
+  return pid;
+}
+
+export function writeSupervisorPid(pid: number, startDir = process.cwd()): void {
+  const startTime = getProcessStartTime(pid);
+  if (!startTime) {
+    throw new Error(`Cannot read start time for pid ${pid}; refusing to write supervisor.pid`);
+  }
+  fs.writeFileSync(getSupervisorPidPath(startDir), `${pid}:${startTime}`);
+}
+
+export function removeSupervisorPid(startDir = process.cwd()): void {
+  const p = getSupervisorPidPath(startDir);
+  if (fs.existsSync(p)) {
+    try {
+      fs.unlinkSync(p);
+    } catch {
+      // best-effort cleanup
+    }
+  }
+}