claude-simple 0.1.0 → 0.2.1

package/src/auto-update.js

@@ -0,0 +1,215 @@
+/**
+ * Optional self-update against the public npm registry.
+ *
+ * Env:
+ *   AUTO_UPDATE=0|false|off     disable (default: enabled for edge client)
+ *   AUTO_UPDATE_INTERVAL_HOURS  check interval, default 12 (half day)
+ *   AUTO_UPDATE_PACKAGE         package name, default claude-simple
+ *   AUTO_UPDATE_CHANNEL         dist-tag, default latest
+ *   AUTO_UPDATE_IDLE_WAIT_MS    wait for agents to finish before applying, default 30min
+ *   AUTO_UPDATE_APPLY=0         only log when newer; do not install/restart
+ */
+import { spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.join(__dirname, '..');
+
+function envBool(name, defaultOn) {
+  const v = process.env[name];
+  if (v == null || v === '') return defaultOn;
+  return !/^(0|false|off|no)$/i.test(String(v));
+}
+
+function readLocalVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+    return String(pkg.version || '0.0.0');
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/** semver-ish compare: a > b → 1, a < b → -1, eq → 0 */
+export function cmpSemver(a, b) {
+  const pa = String(a).replace(/^v/, '').split(/[.+-]/).map((x) => parseInt(x, 10) || 0);
+  const pb = String(b).replace(/^v/, '').split(/[.+-]/).map((x) => parseInt(x, 10) || 0);
+  const n = Math.max(pa.length, pb.length);
+  for (let i = 0; i < n; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+async function fetchLatestVersion(pkgName, tag) {
+  const url = `https://registry.npmjs.org/${encodeURIComponent(pkgName)}`;
+  const res = await fetch(url, {
+    headers: { Accept: 'application/json', 'User-Agent': 'claude-simple-auto-update' },
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!res.ok) throw new Error(`registry HTTP ${res.status}`);
+  const data = await res.json();
+  const ver = data?.['dist-tags']?.[tag] || data?.['dist-tags']?.latest;
+  if (!ver) throw new Error('no dist-tag on registry');
+  return String(ver);
+}
+
+/** Detect install layout: global npm vs local/source tree. */
+function detectInstallMode() {
+  const entry = process.argv[1] ? path.resolve(process.argv[1]) : '';
+  const inGlobal = /[/\\]node_modules[/\\]claude-simple[/\\]/.test(entry)
+    || /[/\\]lib[/\\]node_modules[/\\]claude-simple[/\\]/.test(PKG_ROOT);
+  // Prefer global update when package lives under a node_modules tree named claude-simple
+  if (inGlobal || /[/\\]node_modules[/\\]claude-simple$/.test(PKG_ROOT)) {
+    return { mode: 'global', cwd: process.cwd() };
+  }
+  return { mode: 'local', cwd: PKG_ROOT };
+}
+
+function runNpmInstall(mode, pkgName, version, cwd) {
+  const spec = `${pkgName}@${version}`;
+  const args = mode === 'global'
+    ? ['install', '-g', spec, '--no-fund', '--no-audit']
+    : ['install', spec, '--no-fund', '--no-audit', '--prefix', cwd];
+  return new Promise((resolve, reject) => {
+    console.log(`[auto-update] running: npm ${args.join(' ')}`);
+    const child = spawn('npm', args, {
+      cwd: mode === 'global' ? osHomedir() : cwd,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (d) => { out += d; process.stdout.write(d); });
+    child.stderr.on('data', (d) => { err += d; process.stderr.write(d); });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) resolve({ out, err });
+      else reject(new Error(`npm exited ${code}: ${(err || out).slice(-500)}`));
+    });
+  });
+}
+
+function osHomedir() {
+  return process.env.HOME || process.env.USERPROFILE || PKG_ROOT;
+}
+
+/**
+ * @param {object} opts
+ * @param {() => boolean} [opts.isBusy]  return true while agent turn is running
+ * @param {boolean} [opts.enabled]
+ * @param {string} [opts.role]  log label
+ */
+export function startAutoUpdate(opts = {}) {
+  const enabled = opts.enabled != null ? opts.enabled : envBool('AUTO_UPDATE', true);
+  if (!enabled) {
+    console.log('[auto-update] disabled (AUTO_UPDATE=0)');
+    return { stop() {} };
+  }
+
+  const intervalHours = Math.max(0.25, parseFloat(process.env.AUTO_UPDATE_INTERVAL_HOURS || '12') || 12);
+  const intervalMs = intervalHours * 3600 * 1000;
+  const pkgName = process.env.AUTO_UPDATE_PACKAGE || 'claude-simple';
+  const channel = process.env.AUTO_UPDATE_CHANNEL || 'latest';
+  const apply = envBool('AUTO_UPDATE_APPLY', true);
+  const idleWaitMs = Math.max(60_000, parseInt(process.env.AUTO_UPDATE_IDLE_WAIT_MS || String(30 * 60 * 1000), 10) || 30 * 60 * 1000);
+  const isBusy = typeof opts.isBusy === 'function' ? opts.isBusy : () => false;
+  const role = opts.role || 'process';
+
+  let stopped = false;
+  let timer = null;
+  let applying = false;
+  const localVersion = readLocalVersion();
+
+  console.log(
+    `[auto-update] enabled · local=${localVersion} · check every ${intervalHours}h · package=${pkgName}@${channel} · apply=${apply}`,
+  );
+
+  async function waitUntilIdle() {
+    const deadline = Date.now() + idleWaitMs;
+    while (Date.now() < deadline) {
+      if (stopped) return false;
+      if (!isBusy()) return true;
+      console.log('[auto-update] agent busy — waiting before apply…');
+      await new Promise((r) => setTimeout(r, 15_000));
+    }
+    console.warn('[auto-update] idle wait timed out; applying anyway');
+    return true;
+  }
+
+  async function checkOnce() {
+    if (stopped || applying) return;
+    try {
+      const latest = await fetchLatestVersion(pkgName, channel);
+      const cmp = cmpSemver(latest, localVersion);
+      if (cmp <= 0) {
+        console.log(`[auto-update] up to date (${localVersion}, registry ${latest})`);
+        return;
+      }
+      console.log(`[auto-update] new version available: ${localVersion} → ${latest}`);
+      if (!apply) {
+        console.log('[auto-update] AUTO_UPDATE_APPLY=0 — skip install');
+        return;
+      }
+
+      applying = true;
+      await waitUntilIdle();
+      if (stopped) return;
+
+      const { mode, cwd } = detectInstallMode();
+      console.log(`[auto-update] install mode=${mode} root=${PKG_ROOT}`);
+
+      // Global install when package is under node_modules; else npm install in package root
+      if (mode === 'global') {
+        await runNpmInstall('global', pkgName, latest, cwd);
+      } else {
+        // Source / linked tree: pull package.json version bump via npm update in place
+        await runNpmInstall('local', pkgName, latest, cwd);
+        // If we're running from a git checkout that *is* the package (not a dependency),
+        // local `npm install claude-simple@x` only updates node_modules — won't replace this tree.
+        // For git checkouts, pull via npm pack is wrong; log and skip restart unless global.
+        const pkgJsonName = (() => {
+          try { return JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).name; }
+          catch { return null; }
+        })();
+        if (pkgJsonName === pkgName && !/node_modules/.test(PKG_ROOT)) {
+          console.warn(
+            '[auto-update] running from source checkout — npm cannot overwrite this tree. '
+            + 'Use `npm install -g claude-simple` for auto-apply, or pull git + restart manually.',
+          );
+          applying = false;
+          return;
+        }
+      }
+
+      console.log(`[auto-update] installed ${latest}; restarting ${role} (exit 0 — supervisor should relaunch)`);
+      // Give logs a moment to flush; systemd Restart= will bring us back on new code
+      setTimeout(() => process.exit(0), 500);
+    } catch (e) {
+      console.warn(`[auto-update] check failed: ${e.message || e}`);
+      applying = false;
+    }
+  }
+
+  // First check after a short delay (don't compete with boot / hub connect)
+  const firstDelay = Math.min(60_000, Math.max(15_000, intervalMs / 100));
+  timer = setTimeout(function tick() {
+    checkOnce().finally(() => {
+      if (stopped) return;
+      timer = setTimeout(tick, intervalMs);
+    });
+  }, firstDelay);
+  if (typeof timer.unref === 'function') timer.unref();
+
+  return {
+    stop() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+    },
+    checkNow: checkOnce,
+    localVersion,
+  };
+}

package/src/runtime/approvals.js

@@ -0,0 +1,67 @@
+/**
+ * In-flight tool permission requests (Claude canUseTool bridge).
+ * requestId → { resolve, reject, sessionId, createdAt }
+ */
+
+const pending = new Map();
+
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+
+/**
+ * @param {string} requestId
+ * @param {string | null} sessionId
+ * @param {number} [ttlMs]
+ * @returns {Promise<{ allow: boolean, always?: boolean }>}
+ */
+export function waitForApproval(requestId, sessionId, ttlMs = DEFAULT_TTL_MS) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pending.delete(requestId);
+      resolve({ allow: false, always: false, timeout: true });
+    }, ttlMs);
+
+    pending.set(requestId, {
+      resolve: (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      reject: (e) => {
+        clearTimeout(timer);
+        reject(e);
+      },
+      sessionId: sessionId || null,
+      createdAt: Date.now(),
+    });
+  });
+}
+
+/**
+ * @param {string} requestId
+ * @param {{ allow: boolean, always?: boolean }} decision
+ * @returns {boolean}
+ */
+export function resolveApproval(requestId, decision) {
+  const entry = pending.get(requestId);
+  if (!entry) return false;
+  pending.delete(requestId);
+  entry.resolve({
+    allow: !!decision.allow,
+    always: !!decision.always,
+  });
+  return true;
+}
+
+/** Drop pending approvals for a session (on interrupt). */
+export function cancelApprovalsForSession(sessionId) {
+  if (!sessionId) return;
+  for (const [id, entry] of pending) {
+    if (entry.sessionId === sessionId || entry.sessionId == null) {
+      pending.delete(id);
+      entry.resolve({ allow: false, always: false, cancelled: true });
+    }
+  }
+}
+
+export function pendingApprovalCount() {
+  return pending.size;
+}

package/src/runtime/outbox.js

@@ -0,0 +1,143 @@
+/**
+ * Low-pressure WebSocket outbox.
+ * - Coalesces assistant/thought deltas
+ * - Optionally packs several small events into one `batch` frame
+ * - Flushes on size, time, or non-mergeable event
+ */
+
+import { UI_EVENT } from './protocol.js';
+
+const DELTA_TYPES = new Set([
+  UI_EVENT.ASSISTANT_DELTA,
+  UI_EVENT.THOUGHT_DELTA,
+  'shell-output',
+]);
+
+/**
+ * @param {(data: object) => void} rawSend  — must JSON-send one frame
+ * @param {object} [opts]
+ */
+export function createOutbox(rawSend, opts = {}) {
+  const maxWait = opts.maxWait ?? 45;
+  const maxDeltaChars = opts.maxDeltaChars ?? 640;
+  const maxBatchItems = opts.maxBatchItems ?? 12;
+  const maxBatchBytes = opts.maxBatchBytes ?? 8_000;
+  const enableBatch = opts.enableBatch !== false;
+
+  /** @type {object | null} */
+  let pendingDelta = null;
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let deltaTimer = null;
+  /** @type {object[]} */
+  let batch = [];
+  let batchBytes = 0;
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let batchTimer = null;
+
+  function emitFrame(frame) {
+    if (!frame) return;
+    try {
+      rawSend(frame);
+    } catch { /* ignore closed socket */ }
+  }
+
+  function flushBatch() {
+    if (batchTimer) {
+      clearTimeout(batchTimer);
+      batchTimer = null;
+    }
+    if (!batch.length) return;
+    const items = batch;
+    batch = [];
+    batchBytes = 0;
+    if (items.length === 1) {
+      emitFrame(items[0]);
+    } else {
+      emitFrame({ type: UI_EVENT.BATCH, items });
+    }
+  }
+
+  function enqueue(frame) {
+    if (!enableBatch) {
+      emitFrame(frame);
+      return;
+    }
+    // Control / terminal events go out immediately (after draining batch)
+    const urgent = frame.type === 'error'
+      || frame.type === 'complete'
+      || frame.type === 'result'
+      || frame.type === 'permission_request'
+      || frame.type === 'session-created'
+      || frame.type === 'run-status'
+      || frame.type === 'abort-result'
+      || frame.type === 'shell-exit';
+    if (urgent) {
+      flushBatch();
+      emitFrame(frame);
+      return;
+    }
+
+    let size;
+    try {
+      size = JSON.stringify(frame).length;
+    } catch {
+      size = 256;
+    }
+    batch.push(frame);
+    batchBytes += size;
+    if (batch.length >= maxBatchItems || batchBytes >= maxBatchBytes) {
+      flushBatch();
+      return;
+    }
+    if (!batchTimer) batchTimer = setTimeout(flushBatch, maxWait);
+  }
+
+  function flushDelta() {
+    if (deltaTimer) {
+      clearTimeout(deltaTimer);
+      deltaTimer = null;
+    }
+    if (!pendingDelta) return;
+    const d = pendingDelta;
+    pendingDelta = null;
+    enqueue(d);
+  }
+
+  /**
+   * Accept a UI event (or null to drop).
+   * @param {object | null | undefined} event
+   */
+  function send(event) {
+    if (!event) return;
+
+    if (DELTA_TYPES.has(event.type)) {
+      // Merge consecutive deltas of same type (+ same agent/stream key)
+      const key = `${event.type}|${event.agent || ''}|${event.stream || ''}`;
+      if (pendingDelta) {
+        const pKey = `${pendingDelta.type}|${pendingDelta.agent || ''}|${pendingDelta.stream || ''}`;
+        if (pKey === key) {
+          pendingDelta.data = (pendingDelta.data || '') + (event.data || '');
+          if ((pendingDelta.data || '').length >= maxDeltaChars) flushDelta();
+          else if (!deltaTimer) deltaTimer = setTimeout(flushDelta, maxWait);
+          return;
+        }
+        flushDelta();
+      }
+      pendingDelta = { ...event, data: event.data || '' };
+      if ((pendingDelta.data || '').length >= maxDeltaChars) flushDelta();
+      else if (!deltaTimer) deltaTimer = setTimeout(flushDelta, maxWait);
+      return;
+    }
+
+    // Non-delta: flush coalesced text first so order stays correct
+    flushDelta();
+    enqueue(event);
+  }
+
+  function flush() {
+    flushDelta();
+    flushBatch();
+  }
+
+  return { send, flush };
+}

package/src/runtime/protocol.js

@@ -0,0 +1,224 @@
+/**
+ * Typed control-plane commands + canonical runtime events.
+ * Inspired by T3's orchestration/adapters split, kept intentionally thin.
+ *
+ * Client → server: Command
+ * Server → client: RuntimeEvent (optionally wrapped in `batch`)
+ */
+
+/** @typedef {'turn.start'|'turn.interrupt'|'approval.respond'|'shell.exec'|'session.subscribe'} CommandType */
+
+/**
+ * Normalize any inbound WS message into a command, or null if not a control command.
+ * Keeps legacy aliases working (agent-command, abort-session, …).
+ */
+export function normalizeCommand(msg) {
+  if (!msg || typeof msg !== 'object') return null;
+
+  // New shape: { type: 'command', cmd: 'turn.start', ... }
+  if (msg.type === 'command' && msg.cmd) {
+    return {
+      cmd: msg.cmd,
+      id: msg.id || null,
+      agent: msg.agent || msg.options?.agent || 'claude',
+      command: msg.command ?? msg.prompt ?? '',
+      options: msg.options || {},
+      sessionId: msg.sessionId || msg.options?.sessionId || null,
+      requestId: msg.requestId || null,
+      allow: msg.allow,
+      always: msg.always,
+      cwd: msg.cwd || msg.options?.cwd || null,
+    };
+  }
+
+  if (msg.type === 'claude-command' || msg.type === 'agent-command') {
+    return {
+      cmd: 'turn.start',
+      id: msg.id || null,
+      agent: msg.agent || msg.options?.agent || 'claude',
+      command: msg.command || '',
+      options: msg.options || {},
+      sessionId: msg.options?.sessionId || null,
+      requestId: null,
+      allow: undefined,
+      always: false,
+      cwd: msg.options?.cwd || null,
+    };
+  }
+
+  if (msg.type === 'abort-session') {
+    return {
+      cmd: 'turn.interrupt',
+      id: msg.id || null,
+      agent: null,
+      command: '',
+      options: {},
+      sessionId: msg.sessionId || null,
+      requestId: null,
+      allow: undefined,
+      always: false,
+      cwd: null,
+    };
+  }
+
+  if (msg.type === 'claude-permission-response' || msg.type === 'approval.respond') {
+    return {
+      cmd: 'approval.respond',
+      id: msg.id || null,
+      agent: null,
+      command: '',
+      options: {},
+      sessionId: msg.sessionId || null,
+      requestId: msg.requestId || msg.request_id,
+      allow: msg.allow !== false && msg.allow !== 0 && msg.allow !== '0',
+      always: !!msg.always,
+      cwd: null,
+    };
+  }
+
+  if (msg.type === 'shell-command') {
+    return {
+      cmd: 'shell.exec',
+      id: msg.id || null,
+      agent: null,
+      command: msg.command || '',
+      options: {},
+      sessionId: null,
+      requestId: null,
+      allow: undefined,
+      always: false,
+      cwd: msg.cwd || null,
+    };
+  }
+
+  if (msg.type === 'subscribe') {
+    return {
+      cmd: 'session.subscribe',
+      id: msg.id || null,
+      agent: null,
+      command: '',
+      options: {},
+      sessionId: msg.sessionId || null,
+      requestId: null,
+      allow: undefined,
+      always: false,
+      cwd: null,
+    };
+  }
+
+  return null;
+}
+
+/** Event types the UI understands today (kept stable for back-compat). */
+export const UI_EVENT = {
+  SESSION_CREATED: 'session-created',
+  ASSISTANT: 'assistant',
+  ASSISTANT_STREAM_START: 'assistant_stream_start',
+  ASSISTANT_DELTA: 'assistant_delta',
+  ASSISTANT_STREAM_END: 'assistant_stream_end',
+  THOUGHT_STREAM_START: 'thought_stream_start',
+  THOUGHT_DELTA: 'thought_delta',
+  THOUGHT_STREAM_END: 'thought_stream_end',
+  RESULT: 'result',
+  COMPLETE: 'complete',
+  ERROR: 'error',
+  STATUS: 'status',
+  PERMISSION_REQUEST: 'permission_request',
+  PERMISSION_RESOLVED: 'permission_resolved',
+  SHELL_START: 'shell-start',
+  SHELL_OUTPUT: 'shell-output',
+  SHELL_EXIT: 'shell-exit',
+  RUN_STATUS: 'run-status',
+  ABORT_RESULT: 'abort-result',
+  BATCH: 'batch',
+  PING: 'ping',
+  PONG: 'pong',
+};
+
+/**
+ * Compact tool_use inputs before they hit the wire (mobile tunnel cost).
+ * @param {unknown} input
+ * @param {number} [max=1200]
+ */
+export function compactToolInput(input, max = 1200) {
+  if (input == null) return input;
+  let raw;
+  try {
+    raw = typeof input === 'string' ? input : JSON.stringify(input);
+  } catch {
+    raw = String(input);
+  }
+  if (raw.length <= max) return input;
+  return { _truncated: true, preview: raw.slice(0, max), bytes: raw.length };
+}
+
+/**
+ * Map a loose agent emit into a UI event, dropping unknown SDK noise.
+ * Returns null to drop the frame entirely.
+ */
+export function mapAgentEmit(data, { agent, compactTools = true } = {}) {
+  if (!data || typeof data !== 'object') return null;
+  const t = data.type;
+
+  // Already a UI event we know
+  const known = new Set([
+    'session-created', 'assistant', 'assistant_stream_start', 'assistant_delta',
+    'assistant_stream_end', 'thought_stream_start', 'thought_delta', 'thought_stream_end',
+    'result', 'complete', 'error', 'status', 'permission_request', 'permission_resolved',
+    'shell-start', 'shell-output', 'shell-exit', 'run-status', 'abort-result',
+  ]);
+  if (known.has(t)) {
+    const out = { ...data };
+    if (agent && !out.agent) out.agent = agent;
+    if (compactTools && out.type === 'assistant' && Array.isArray(out.message?.content)) {
+      out.message = {
+        ...out.message,
+        content: out.message.content.map((b) => {
+          if (b?.type === 'tool_use' && b.input != null) {
+            return { ...b, input: compactToolInput(b.input) };
+          }
+          return b;
+        }),
+      };
+    }
+    return out;
+  }
+
+  // Claude Agent SDK message shapes → UI
+  if (t === 'system' && data.session_id) {
+    return { type: 'session-created', sessionId: data.session_id, agent: agent || 'claude' };
+  }
+
+  if (t === 'assistant' && data.message) {
+    // SDK assistant message — keep but compact tools
+    return mapAgentEmit({ type: 'assistant', message: data.message, ts: data.ts }, { agent, compactTools });
+  }
+
+  if (t === 'result') {
+    return {
+      type: 'result',
+      is_error: !!data.is_error,
+      usage: data.usage || null,
+      sessionId: data.session_id || data.sessionId || null,
+      agent: agent || data.agent || 'claude',
+      result: typeof data.result === 'string' && data.result.length > 4000
+        ? data.result.slice(0, 4000) + '…'
+        : data.result,
+    };
+  }
+
+  // Drop high-chatter / unused SDK frames (stream_event, user, tool_progress, auth, …)
+  if (
+    t === 'stream_event'
+    || t === 'user'
+    || t === 'tool_progress'
+    || t === 'auth_status'
+    || t === 'rate_limit_event'
+    || t === 'system' // non-session system notices
+  ) {
+    return null;
+  }
+
+  // Unknown — drop to cut noise (was previously forwarded wholesale from Claude)
+  return null;
+}