@remcp/runtime 0.2.0

package/src/config.mjs

@@ -0,0 +1,84 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { expandHome } from './util.mjs';
+
+const configDir = process.env.REMCP_RUNTIME_CONFIG_DIR || path.join(os.homedir(), '.config', 'remcp');
+export const runtimeConfigPath = path.join(configDir, 'runtime.json');
+export const runtimeConfigDir = configDir;
+
+function readConfigFile() {
+  try { return JSON.parse(readFileSync(runtimeConfigPath, 'utf8')); } catch { return {}; }
+}
+
+const file = readConfigFile();
+
+function stringList(value, fallback = []) {
+  const source = Array.isArray(value) ? value : typeof value === 'string' ? value.split(',') : fallback;
+  return source.map(item => String(item).trim()).filter(Boolean);
+}
+
+function positiveNumber(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function booleanValue(value, fallback) {
+  if (value === undefined || value === null || value === '') return fallback;
+  if (typeof value === 'boolean') return value;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on', 'enabled'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off', 'disabled'].includes(normalized)) return false;
+  return fallback;
+}
+
+const DANGEROUS_MODES = ['block', 'warn', 'allow'];
+
+function dangerousMode(value, fallback = 'block') {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  return DANGEROUS_MODES.includes(normalized) ? normalized : fallback;
+}
+
+const allowedRoots = stringList(process.env.REMCP_RUNTIME_ALLOWED_ROOTS ?? file.allowedRoots)
+  .map(root => path.resolve(expandHome(root)));
+
+// Telemetry is opt-out, matching the ReMCP client: it is on unless the user (or the
+// ReMCP agent that spawned this runtime) turns it off. It never sends file paths,
+// command strings, arguments, or tool output - only tool names, timings and outcomes.
+const telemetryDisabled = booleanValue(process.env.REMCP_RUNTIME_DISABLE_TELEMETRY, false);
+const telemetryEnabled = telemetryDisabled
+  ? false
+  : booleanValue(process.env.REMCP_RUNTIME_TELEMETRY ?? file.telemetryEnabled, true);
+
+export const runtimeConfig = Object.freeze({
+  allowedRoots: Object.freeze(allowedRoots),
+  blockedCommands: Object.freeze(stringList(process.env.REMCP_RUNTIME_BLOCKED_COMMANDS ?? file.blockedCommands)),
+  dangerousCommands: dangerousMode(process.env.REMCP_RUNTIME_DANGEROUS_COMMANDS ?? file.dangerousCommands),
+  maxOutputBytes: positiveNumber(process.env.REMCP_RUNTIME_MAX_OUTPUT_BYTES ?? file.maxOutputBytes, 1024 * 1024),
+  maxReadLines: positiveNumber(process.env.REMCP_RUNTIME_MAX_READ_LINES ?? file.maxReadLines, 2000),
+  maxBufferedLines: positiveNumber(process.env.REMCP_RUNTIME_MAX_BUFFERED_LINES ?? file.maxBufferedLines, 50000),
+  maxWriteBytes: positiveNumber(process.env.REMCP_RUNTIME_MAX_WRITE_BYTES ?? file.maxWriteBytes, 8 * 1024 * 1024),
+  defaultShell: String(process.env.REMCP_RUNTIME_SHELL || file.defaultShell || '').trim(),
+  name: String(process.env.REMCP_RUNTIME_NAME || file.name || os.hostname()).trim(),
+  telemetryEnabled,
+});
+
+export function describeConfig() {
+  return {
+    name: runtimeConfig.name,
+    platform: process.platform,
+    arch: process.arch,
+    node: process.versions.node,
+    configFile: runtimeConfigPath,
+    allowedRoots: [...runtimeConfig.allowedRoots],
+    blockedCommands: [...runtimeConfig.blockedCommands],
+    dangerousCommands: runtimeConfig.dangerousCommands,
+    maxOutputBytes: runtimeConfig.maxOutputBytes,
+    maxReadLines: runtimeConfig.maxReadLines,
+    maxBufferedLines: runtimeConfig.maxBufferedLines,
+    maxWriteBytes: runtimeConfig.maxWriteBytes,
+    defaultShell: runtimeConfig.defaultShell || null,
+    telemetryEnabled: runtimeConfig.telemetryEnabled,
+    telemetryTransport: 'paired-agent-only',
+  };
+}

package/src/index.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { toolDefinitions } from './catalog.mjs';
+import { describeConfig, runtimeConfigDir } from './config.mjs';
+import { invokeTool } from './invoke.mjs';
+import { shutdownSessions, startSessionSweeper } from './sessions.mjs';
+import { flush, setTelemetrySink, shutdownTelemetry, telemetryEnabled } from './telemetry.mjs';
+import { VERSION } from './version.mjs';
+
+// The MCP SDK is imported lazily so that `--help`, `--version`, `--print-tools` and
+// `--describe` work from a bare checkout or a published tarball with no node_modules.
+// That is what lets CI diff the advertised tool contract against the package users get.
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write([
+    'ReMCP local device runtime',
+    '',
+    'Usage: remcp-runtime [--print-tools] [--describe] [--version]',
+    '',
+    'The runtime is normally started by the ReMCP device agent and speaks MCP over stdio.',
+    'It executes file, search, terminal, and process tools locally on this computer.',
+    '',
+    'Usage metrics are opt-out: only tool names, timings and outcomes are collected, and they',
+    'travel to your own ReMCP account through the already-authenticated paired agent. Nothing is',
+    'sent to a third party, there is no install ping, and there are no remote feature flags.',
+    'Disable with `remcp telemetry off`, REMCP_RUNTIME_DISABLE_TELEMETRY=1, or',
+    '"telemetryEnabled": false in runtime.json.',
+    '',
+  ].join('\n'));
+  process.exit(0);
+}
+
+if (args.includes('--version')) {
+  process.stdout.write(`${VERSION}\n`);
+  process.exit(0);
+}
+
+if (args.includes('--print-tools')) {
+  process.stdout.write(`${JSON.stringify(toolDefinitions.map(({ name, title, description, inputSchema, annotations }) => ({ name, title, description, inputSchema, annotations })), null, 2)}\n`);
+  process.exit(0);
+}
+
+if (args.includes('--describe')) {
+  process.stdout.write(`${JSON.stringify({ version: VERSION, tools: toolDefinitions.length, ...describeConfig() }, null, 2)}\n`);
+  process.exit(0);
+}
+
+function announceTelemetryOnce() {
+  if (!telemetryEnabled()) return;
+  const marker = path.join(runtimeConfigDir, '.telemetry-notice');
+  try {
+    if (existsSync(marker)) return;
+    mkdirSync(runtimeConfigDir, { recursive: true, mode: 0o700 });
+    writeFileSync(marker, `${new Date().toISOString()}\n`, { mode: 0o600 });
+  } catch { return; }
+  console.error('ReMCP runtime: anonymous usage metrics are on (tool names, timings, outcomes only - never file paths, commands or output). They go to your own ReMCP account through the paired agent. Disable with `remcp telemetry off`.');
+}
+
+const { Server } = await import('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+const { CallToolRequestSchema, ListToolsRequestSchema } = await import('@modelcontextprotocol/sdk/types.js');
+
+const server = new Server(
+  { name: 'remcp-runtime', version: VERSION },
+  {
+    capabilities: { tools: {}, experimental: { 'remcp/telemetry': { version: 1, optOut: true } } },
+    instructions: [
+      'This runtime executes file, search, terminal, and process tools locally on a computer that its owner paired with ReMCP.',
+      'Inspect before changing: read and list first, then write, edit, move, or run commands only when the user asked for that side effect.',
+      'Paths are absolute or resolve against the runtime working directory; prefer absolute paths.',
+      'Commands matching the built-in catastrophic-command guardrail are refused before they run.',
+    ].join(' '),
+  },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: toolDefinitions.map(({ name, title, description, inputSchema, annotations }) => ({ name, title, description, inputSchema, annotations })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async request => {
+  return invokeTool(request.params.name, request.params.arguments);
+});
+
+// Telemetry leaves this process only as an MCP notification to the agent that started
+// it. The runtime never opens a network connection of its own.
+setTelemetrySink(async payload => {
+  await server.notification({ method: 'notifications/remcp/telemetry', params: payload });
+});
+
+async function shutdown(code = 0) {
+  shutdownSessions();
+  try { await flush(); } catch {}
+  shutdownTelemetry();
+  try { await server.close(); } catch {}
+  process.exit(code);
+}
+
+process.on('SIGINT', () => void shutdown(0));
+process.on('SIGTERM', () => void shutdown(0));
+process.on('exit', () => { shutdownSessions(); shutdownTelemetry(); });
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+startSessionSweeper();
+announceTelemetryOnce();
+console.error(`ReMCP runtime ${VERSION} ready with ${toolDefinitions.length} tools`);

package/src/invoke.mjs

@@ -0,0 +1,31 @@
+import { toolHandlers } from './catalog.mjs';
+import { recordEvent } from './telemetry.mjs';
+import { ToolError, text } from './util.mjs';
+
+export function hasTool(name) {
+  return toolHandlers.has(name);
+}
+
+function errorKind(error) {
+  if (error instanceof ToolError) return 'tool_error';
+  const code = error?.code;
+  return typeof code === 'string' && code ? code.slice(0, 32) : 'runtime_error';
+}
+
+export async function invokeTool(name, args = {}) {
+  const started = performance.now();
+  const definition = toolHandlers.get(name);
+  if (!definition) {
+    recordEvent('tool_call', { tool: 'unknown_tool', success: false, errorKind: 'unknown_tool', durationMs: 0 });
+    return text(`Unknown tool: ${name}`, true);
+  }
+  try {
+    const result = await definition.handler(args || {});
+    recordEvent('tool_call', { tool: definition.name, durationMs: performance.now() - started, success: result?.isError !== true });
+    return result;
+  } catch (error) {
+    recordEvent('tool_call', { tool: definition.name, durationMs: performance.now() - started, success: false, errorKind: errorKind(error) });
+    if (error instanceof ToolError) return text(error.message, true);
+    return text(`Tool ${name} failed: ${error instanceof Error ? error.message : String(error)}`, true);
+  }
+}

package/src/policy.mjs

@@ -0,0 +1,55 @@
+import { runtimeConfig } from './config.mjs';
+import { fail } from './util.mjs';
+
+// Catastrophic host-level commands that a remote model should never run by accident.
+// This is a guardrail, not a sandbox: it protects against obvious mistakes and
+// prompt-injected one-liners, not against a determined adversary who already has
+// shell access through the paired account.
+const DANGEROUS_PATTERNS = [
+  { id: 'filesystem-format', description: 'formats a filesystem', pattern: /\bmkfs(\.[a-z0-9]+)?\b/i },
+  { id: 'raw-disk-write', description: 'writes raw data to a block device', pattern: /\bdd\b[^\n]*\bof=\s*\/dev\//i },
+  { id: 'disk-partition', description: 'repartitions a disk', pattern: /\b(fdisk|sfdisk|cfdisk|parted|diskpart)\b/i },
+  { id: 'redirect-to-device', description: 'redirects output into a block device', pattern: />>?\s*\/dev\/(sd|hd|vd|nvme|mmcblk|disk)/i },
+  { id: 'host-power', description: 'powers off or reboots the machine', pattern: /\b(shutdown|reboot|halt|poweroff)\b/i },
+  { id: 'init-runlevel', description: 'changes the init runlevel', pattern: /\binit\s+[06]\b/i },
+  { id: 'fork-bomb', description: 'starts a fork bomb', pattern: /:\s*\(\s*\)\s*\{[^}]*\}\s*;\s*:/ },
+  { id: 'recursive-root-delete', description: 'recursively deletes a root or home path', pattern: /\brm\b(?=[^\n]*\s-[a-z]*r)(?=[^\n]*\s-[a-z]*f)[^\n]*\s(\/|\/\*|~|\$HOME|\$\{HOME\})(\s|$)/i },
+  { id: 'chmod-root', description: 'recursively rewrites permissions on a root path', pattern: /\bchmod\b[^\n]*\s(\/|\/\*)(\s|$)/i },
+  { id: 'chown-root', description: 'recursively rewrites ownership on a root path', pattern: /\bchown\b[^\n]*\s(\/|\/\*)(\s|$)/i },
+  { id: 'history-rewrite', description: 'clears shell history to hide activity', pattern: /\b(history\s+-c|shred\b[^\n]*\.bash_history|>\s*~?\/?\.bash_history)/i },
+  { id: 'windows-destructive', description: 'destroys Windows system state', pattern: /\b(format|diskpart|bcdedit|cipher\s+\/w)\b/i },
+];
+
+function normalize(command) {
+  return String(command).replace(/\s+/g, ' ').trim();
+}
+
+export function checkCommand(command) {
+  const normalized = normalize(command);
+  const findings = [];
+  for (const blocked of runtimeConfig.blockedCommands) {
+    if (normalized.toLowerCase().includes(blocked.toLowerCase())) findings.push({ id: 'policy', description: blocked, source: 'device-policy' });
+  }
+  if (runtimeConfig.dangerousCommands !== 'allow') {
+    for (const entry of DANGEROUS_PATTERNS) {
+      if (entry.pattern.test(normalized)) findings.push({ id: entry.id, description: entry.description, source: 'builtin' });
+    }
+  }
+  if (!findings.length) return { warned: false, mode: runtimeConfig.dangerousCommands };
+  const unique = [...new Map(findings.map(item => [item.id + item.description, item])).values()];
+  if (runtimeConfig.dangerousCommands === 'warn' && unique.every(item => item.source === 'builtin')) {
+    return { warned: true, mode: 'warn', findings: unique };
+  }
+  return { blocked: true, mode: runtimeConfig.dangerousCommands, findings: unique };
+}
+
+export function assertAllowedCommand(command) {
+  const verdict = checkCommand(command);
+  if (verdict.blocked) {
+    const detail = verdict.findings.map(item => item.description).join(', ');
+    fail(`Command blocked by ReMCP device policy (${detail}). Set REMCP_RUNTIME_BLOCKED_COMMANDS to adjust the device list, or REMCP_RUNTIME_DANGEROUS_COMMANDS=allow to disable the built-in catastrophic-command guardrail.`);
+  }
+  return verdict;
+}
+
+export const dangerousPatternIds = DANGEROUS_PATTERNS.map(entry => entry.id);

package/src/sessions.mjs

@@ -0,0 +1,219 @@
+import { runtimeConfig } from './config.mjs';
+
+const processSessions = new Map();
+const searchSessions = new Map();
+let searchCounter = 0;
+
+const EXITED_SESSION_TTL_MS = 30 * 60 * 1000;
+
+function trimBuffer(session) {
+  const overflow = session.lines.length - runtimeConfig.maxBufferedLines;
+  if (overflow <= 0) return;
+  session.lines.splice(0, overflow);
+  session.droppedLines += overflow;
+}
+
+function notify(session) {
+  const waiters = session.waiters.splice(0, session.waiters.length);
+  for (const resolve of waiters) resolve();
+}
+
+// A waiter whose timer fires first must remove itself, otherwise finished sessions keep
+// holding closures until the next append (which may never come).
+function waiter(session, timeoutMs) {
+  return new Promise(resolve => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      const index = session.waiters.indexOf(finish);
+      if (index !== -1) session.waiters.splice(index, 1);
+      resolve();
+    };
+    const timer = setTimeout(finish, Math.max(0, timeoutMs));
+    timer.unref?.();
+    session.waiters.push(finish);
+  });
+}
+
+export function createProcessSession({ pid, child, command, shell }) {
+  const session = {
+    pid,
+    child,
+    command,
+    shell,
+    startedAt: Date.now(),
+    finishedAt: null,
+    lines: [],
+    partial: '',
+    lastPartialRead: null,
+    droppedLines: 0,
+    cursor: 0,
+    exitCode: null,
+    signal: null,
+    exited: false,
+    waiters: [],
+    lastActivityAt: Date.now(),
+  };
+  processSessions.set(pid, session);
+  return session;
+}
+
+export function appendProcessOutput(session, chunk) {
+  const combined = session.partial + chunk;
+  const parts = combined.split('\n');
+  session.partial = parts.pop() ?? '';
+  for (const line of parts) session.lines.push(line);
+  trimBuffer(session);
+  session.lastActivityAt = Date.now();
+  notify(session);
+}
+
+export function markProcessExited(session, code, signal) {
+  if (session.partial) {
+    session.lines.push(session.partial);
+    session.partial = '';
+  }
+  session.exited = true;
+  session.exitCode = code;
+  session.signal = signal;
+  session.finishedAt = Date.now();
+  notify(session);
+}
+
+export function getProcessSession(pid) {
+  return processSessions.get(pid) || null;
+}
+
+export function listProcessSessions() {
+  sweep();
+  return [...processSessions.values()].sort((a, b) => a.startedAt - b.startedAt);
+}
+
+export function absoluteLine(session, index) {
+  return session.droppedLines + index + 1;
+}
+
+export function totalLines(session) {
+  return session.droppedLines + session.lines.length + (session.partial ? 1 : 0);
+}
+
+export function readNewOutput(session) {
+  const complete = session.lines.slice(Math.max(0, session.cursor - session.droppedLines));
+  session.cursor = session.droppedLines + session.lines.length;
+  const parts = [...complete];
+  if (session.partial && session.partial !== session.lastPartialRead) parts.push(session.partial);
+  session.lastPartialRead = session.partial || null;
+  return parts;
+}
+
+export function readOutputRange(session, offset, length) {
+  const snapshot = session.lines.concat(session.partial ? [session.partial] : []);
+  const total = session.droppedLines + snapshot.length;
+  const requested = Number.isFinite(Number(offset)) ? Math.trunc(Number(offset)) : 0;
+  let start;
+  let end;
+  if (requested < 0) {
+    start = Math.max(0, snapshot.length + requested);
+    end = snapshot.length;
+  } else {
+    start = Math.max(0, Math.min(requested - session.droppedLines, snapshot.length));
+    end = Math.min(snapshot.length, start + Math.max(1, Math.trunc(length || 200)));
+  }
+  session.cursor = session.droppedLines + session.lines.length;
+  return { slice: snapshot.slice(start, end), start: session.droppedLines + start + 1, end: session.droppedLines + end, total };
+}
+
+export async function waitForProcessActivity(session, timeoutMs) {
+  if (session.exited) return;
+  await waiter(session, timeoutMs);
+}
+
+export async function waitForProcessExit(session, timeoutMs) {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  while (!session.exited && Date.now() < deadline) {
+    await waitForProcessActivity(session, Math.min(100, Math.max(10, deadline - Date.now())));
+  }
+}
+
+export function createSearchSession({ type, pattern, path, filePattern }) {
+  const session = {
+    id: `search-${++searchCounter}`,
+    type,
+    pattern,
+    path,
+    filePattern: filePattern || null,
+    startedAt: Date.now(),
+    finishedAt: null,
+    results: [],
+    status: 'running',
+    error: null,
+    cancel: null,
+    waiters: [],
+    lastActivityAt: Date.now(),
+  };
+  searchSessions.set(session.id, session);
+  return session;
+}
+
+export function appendSearchResults(session, results) {
+  if (!results.length) return;
+  session.results.push(...results);
+  session.lastActivityAt = Date.now();
+  notify(session);
+}
+
+export function finishSearchSession(session, status, error = null) {
+  session.status = status;
+  session.error = error ? String(error) : null;
+  session.finishedAt = Date.now();
+  session.cancel = null;
+  notify(session);
+}
+
+export function getSearchSession(id) {
+  return searchSessions.get(String(id)) || null;
+}
+
+export function listSearchSessions() {
+  sweep();
+  return [...searchSessions.values()].sort((a, b) => a.startedAt - b.startedAt);
+}
+
+export async function waitForSearchResults(session, count, timeoutMs) {
+  if (session.results.length >= count || session.status !== 'running') return;
+  await waiter(session, timeoutMs);
+}
+
+export function sweep(now = Date.now()) {
+  for (const [pid, session] of processSessions) {
+    if (session.exited && session.finishedAt && now - session.finishedAt > EXITED_SESSION_TTL_MS) processSessions.delete(pid);
+  }
+  for (const [id, session] of searchSessions) {
+    if (session.status !== 'running' && session.finishedAt && now - session.finishedAt > EXITED_SESSION_TTL_MS) searchSessions.delete(id);
+  }
+}
+
+// Eviction used to run only inside list_sessions/list_searches, so an agent that never
+// listed them kept abandoned sessions (and their result arrays) in memory forever.
+let sweepTimer = null;
+export function startSessionSweeper(intervalMs = 5 * 60 * 1000) {
+  if (sweepTimer) return;
+  sweepTimer = setInterval(() => sweep(), intervalMs);
+  sweepTimer.unref?.();
+}
+
+export function shutdownSessions() {
+  if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
+  for (const session of processSessions.values()) {
+    if (!session.exited) {
+      try { session.child.kill('SIGKILL'); } catch {}
+    }
+  }
+  for (const session of searchSessions.values()) {
+    if (session.status === 'running' && session.cancel) {
+      try { session.cancel(); } catch {}
+    }
+  }
+}

package/src/telemetry.mjs

@@ -0,0 +1,154 @@
+import process from 'node:process';
+import { runtimeConfig } from './config.mjs';
+import { VERSION } from './version.mjs';
+
+// Event fields are whitelisted: an event can never carry a file path, a command
+// string, tool arguments, or tool output. Only tool names, timings, outcomes and
+// coarse error classes leave this process, and only through the paired ReMCP agent.
+const EVENT_FIELDS = {
+  tool: value => String(value).slice(0, 64),
+  durationMs: value => Math.max(0, Math.round(Number(value))),
+  success: value => value === true,
+  errorKind: value => String(value).slice(0, 48),
+  sessionKind: value => (value === 'process' || value === 'search' ? value : 'other'),
+  reason: value => String(value).slice(0, 48),
+  count: value => Math.max(0, Math.round(Number(value))),
+};
+
+const BUFFER_LIMIT = 250;
+const FLUSH_INTERVAL_MS = 15_000;
+const FLUSH_THRESHOLD = 20;
+
+const state = {
+  enabled: runtimeConfig.telemetryEnabled,
+  buffer: [],
+  sink: null,
+  timer: null,
+  startedAt: Date.now(),
+  dropped: 0,
+  sent: 0,
+  counters: {
+    toolCalls: 0,
+    toolFailures: 0,
+    policyBlocks: 0,
+    sessionsStarted: 0,
+    searchesStarted: 0,
+    bytesWritten: 0,
+    writeDenials: 0,
+  },
+  toolCounts: new Map(),
+};
+
+export function telemetryEnabled() {
+  return state.enabled;
+}
+
+export function telemetryStatus() {
+  return {
+    enabled: state.enabled,
+    transport: 'paired-agent-only',
+    endpoint: null,
+    thirdParty: false,
+    installPing: false,
+    remoteFeatureFlags: false,
+    buffered: state.buffer.length,
+    sentEvents: state.sent,
+    droppedEvents: state.dropped,
+    counters: { ...state.counters },
+    topTools: topTools(5),
+    uptimeSeconds: Math.round((Date.now() - state.startedAt) / 1000),
+  };
+}
+
+function topTools(limit) {
+  return [...state.toolCounts.entries()]
+    .sort((a, b) => b[1].count - a[1].count)
+    .slice(0, limit)
+    .map(([tool, value]) => ({ tool, calls: value.count, failures: value.failures }));
+}
+
+function bump(tool, success) {
+  state.counters.toolCalls += 1;
+  if (!success) state.counters.toolFailures += 1;
+  const entry = state.toolCounts.get(tool) || { count: 0, failures: 0 };
+  entry.count += 1;
+  if (!success) entry.failures += 1;
+  state.toolCounts.set(tool, entry);
+}
+
+export function countEvent(name, amount = 1) {
+  if (Object.hasOwn(state.counters, name)) state.counters[name] += Math.max(0, Math.round(Number(amount) || 0));
+}
+
+function sanitize(detail) {
+  const clean = {};
+  for (const [key, coerce] of Object.entries(EVENT_FIELDS)) {
+    if (detail[key] === undefined || detail[key] === null) continue;
+    const value = coerce(detail[key]);
+    if (value === undefined || (typeof value === 'number' && !Number.isFinite(value))) continue;
+    clean[key] = value;
+  }
+  return clean;
+}
+
+export function recordEvent(event, detail = {}) {
+  const name = String(event).slice(0, 48);
+  if (name === 'tool_call') bump(detail.tool ? String(detail.tool).slice(0, 64) : 'unknown', detail.success === true);
+  if (name === 'policy_block') state.counters.policyBlocks += 1;
+  if (name === 'session_started') state.counters.sessionsStarted += 1;
+  if (name === 'write_denied') state.counters.writeDenials += 1;
+  if (!state.enabled) return;
+  if (state.buffer.length >= BUFFER_LIMIT) {
+    state.dropped += 1;
+    return;
+  }
+  state.buffer.push({ event: name, at: Date.now(), ...sanitize(detail) });
+  if (state.buffer.length >= FLUSH_THRESHOLD) void flush();
+}
+
+export function setTelemetrySink(sink) {
+  state.sink = typeof sink === 'function' ? sink : null;
+  if (state.sink && !state.timer) {
+    state.timer = setInterval(() => void flush(), FLUSH_INTERVAL_MS);
+    state.timer.unref?.();
+  }
+}
+
+export async function flush() {
+  if (!state.sink || !state.buffer.length) return 0;
+  const batch = state.buffer.splice(0, state.buffer.length);
+  try {
+    await state.sink({
+      runtimeVersion: VERSION,
+      node: process.versions.node,
+      platform: process.platform,
+      arch: process.arch,
+      name: runtimeConfig.name,
+      events: batch,
+    });
+    state.sent += batch.length;
+    return batch.length;
+  } catch {
+    // Never lose the process over telemetry, and never grow without bound either.
+    state.dropped += batch.length;
+    return 0;
+  }
+}
+
+export function shutdownTelemetry() {
+  if (state.timer) {
+    clearInterval(state.timer);
+    state.timer = null;
+  }
+  try { state.sink?.({ runtimeVersion: VERSION, platform: process.platform, arch: process.arch, name: runtimeConfig.name, events: state.buffer.splice(0, state.buffer.length) }); } catch {}
+}
+
+export function resetTelemetryForTests() {
+  state.buffer.length = 0;
+  state.dropped = 0;
+  state.sent = 0;
+  state.sink = null;
+  if (state.timer) { clearInterval(state.timer); state.timer = null; }
+  state.toolCounts.clear();
+  for (const key of Object.keys(state.counters)) state.counters[key] = 0;
+}