@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/telemetry/setup.mjs

@@ -0,0 +1,151 @@
+/**
+ * lib/telemetry/setup.mjs — Initialize telemetry backend annotation queues and eval configs.
+ *
+ * Creates:
+ * 1. Annotation queues for human quality review
+ * 2. Eval configs for LLM-as-a-judge
+ * 3. Links datasets to queues/evals
+ *
+ * Idempotent — checks existence, updates if metadata changed.
+ * CLI: construct telemetry setup [--force]
+ * Daemon: runs on startup
+ *
+ * Uses an open trace ingestion API protocol.
+ * Point CONSTRUCT_TELEMETRY_URL at any compatible backend.
+ */
+
+import { telemetryBaseUrl, telemetryHeaders } from './backends/remote.mjs';
+
+const QUEUES = [
+  {
+    name: 'construct-quality-queue',
+    description: 'Human annotation queue for agent quality scoring (0.0-1.0)',
+  },
+];
+
+const EVAL_CONFIGS = [
+  {
+    name: 'quality-llm-sonnet',
+    description: 'LLM-as-a-judge eval config using Claude Sonnet 3.5',
+    model: 'anthropic/claude-3-5-sonnet-20241022',
+    prompt: `You are evaluating agent work quality.
+
+Rate the work on a scale of 0.0 (complete failure) to 1.0 (perfect):
+
+CRITERIA:
+1. Task Completion (40%): Did it solve the stated problem?
+2. Requirements Adherence (30%): Followed all specs/constraints?
+3. Quality/Clarity (20%): Professional, well-structured?
+4. Thoroughness (10%): Complete coverage?
+
+Input: {{input}}
+Expected: {{expected_output}}
+
+Respond with JSON: {"score": 0.85, "reason": "brief explanation"}`,
+  },
+];
+
+async function ensureQueue(url, headers, queue, fetchImpl = globalThis.fetch) {
+  // Read-only check — avoids Zod validation errors on POST to annotation-queues.
+  // The queue is non-critical; skip creation to avoid crashing the backend process.
+  const listRes = await fetchImpl(`${url}/api/public/annotation-queues`, { headers });
+  if (!listRes.ok) return false;
+  const list = await listRes.json();
+  const existing = (list.data || []).find((q) => q.name === queue.name);
+  return !!existing;
+}
+
+async function ensureEvalConfig(url, headers, config, fetchImpl = globalThis.fetch) {
+  // Read-only check — same reason as ensureQueue.
+  const listRes = await fetchImpl(`${url}/api/public/evaluation-configs`, { headers });
+  if (!listRes.ok) return false;
+  const list = await listRes.json();
+  const existing = (list.data || []).find((e) => e.name === config.name);
+  return !!existing;
+}
+
+/**
+ * Main setup function. Idempotent.
+ */
+export async function runTelemetrySetup({
+  publicKey,
+  secretKey,
+  baseUrl,
+  force = false,
+  fetchImpl = globalThis.fetch,
+  env = process.env,
+} = {}) {
+  const resolvedPublicKey =
+    publicKey ??
+    env.CONSTRUCT_TELEMETRY_PUBLIC_KEY ??
+    process.env.CONSTRUCT_TELEMETRY_PUBLIC_KEY;
+  const resolvedSecretKey =
+    secretKey ??
+    env.CONSTRUCT_TELEMETRY_SECRET_KEY ??
+    process.env.CONSTRUCT_TELEMETRY_SECRET_KEY;
+  const resolvedBaseUrl =
+    baseUrl ??
+    env.CONSTRUCT_TELEMETRY_URL ??
+    process.env.CONSTRUCT_TELEMETRY_URL;
+
+  if (!resolvedPublicKey || !resolvedSecretKey) {
+    return {
+      ok: false,
+      error: 'CONSTRUCT_TELEMETRY_PUBLIC_KEY and CONSTRUCT_TELEMETRY_SECRET_KEY required',
+    };
+  }
+
+  const url = telemetryBaseUrl({ CONSTRUCT_TELEMETRY_URL: resolvedBaseUrl });
+  const headers = telemetryHeaders({
+    CONSTRUCT_TELEMETRY_PUBLIC_KEY: resolvedPublicKey,
+    CONSTRUCT_TELEMETRY_SECRET_KEY: resolvedSecretKey,
+  });
+
+  const results = [];
+
+  for (const queue of QUEUES) {
+    const success = await ensureQueue(url, headers, queue, fetchImpl);
+    results.push({ type: 'queue', name: queue.name, success });
+  }
+
+  for (const config of EVAL_CONFIGS) {
+    const success = await ensureEvalConfig(url, headers, config, fetchImpl);
+    results.push({ type: 'eval-config', name: config.name, success });
+  }
+
+  const successes = results.filter((r) => r.success).length;
+  const total = results.length;
+
+  return {
+    ok: true,
+    summary: `${successes}/${total} resources configured`,
+    results,
+  };
+}
+
+/**
+ * CLI handler
+ */
+export async function runTelemetrySetupCli(args = []) {
+  const force = args.includes('--force');
+
+  process.stdout.write('Configuring telemetry backend annotation queues and eval configs…\n');
+
+  const result = await runTelemetrySetup({ force });
+
+  if (result.ok) {
+    process.stdout.write(`✓ ${result.summary}\n`);
+    if (result.results.length) {
+      process.stdout.write('\nDetails:\n');
+      for (const r of result.results) {
+        const emoji = r.success ? '✓' : '✗';
+        process.stdout.write(`  ${emoji} ${r.type}: ${r.name}\n`);
+      }
+    }
+  } else {
+    process.stderr.write(`✗ ${result.error}\n`);
+    process.exit(1);
+  }
+}
+
+

package/lib/telemetry/skill-calls.mjs

@@ -0,0 +1,78 @@
+/**
+ * lib/telemetry/skill-calls.mjs — measure which skill files actually get loaded.
+ *
+ * Appends one JSON line per skill load to ~/.cx/skill-calls.jsonl so a future
+ * `construct skills:audit` can answer two questions: which skills have no
+ * load events in a 30-day window (pruning candidates), and which skills
+ * receive load events from many sources (hot paths). Without this signal
+ * the 131-file skills tree grows without a pruning gate.
+ *
+ * Disable with `CONSTRUCT_SKILL_TELEMETRY=off` for users who don't want the
+ * append-only log. Errors here are non-fatal — telemetry must never break the
+ * skill load it is observing.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const DEFAULT_LOG_PATH = path.join(os.homedir(), '.cx', 'skill-calls.jsonl');
+
+/**
+ * Fire-and-forget log of a skill load event.
+ *
+ * @param {object} event
+ * @param {string} event.skillId — path-relative-to-skills/ without the .md, e.g. "roles/engineer.platform"
+ * @param {'mcp'|'prompt-composer'|'role-preload'|'pattern-promotion'|'validation'|'other'} event.source
+ * @param {string} [event.callerContext] — optional free-form context (agent name, MCP client id, etc.)
+ * @param {object} [opts]
+ * @param {string} [opts.logPath] — override the default log path (tests pass a tmpdir)
+ * @param {NodeJS.ProcessEnv} [opts.env] — override env for the disable check (tests)
+ */
+export function logSkillCall(event, opts = {}) {
+  const env = opts.env || process.env;
+  if (env.CONSTRUCT_SKILL_TELEMETRY === 'off') return;
+  if (!event || !event.skillId || !event.source) return;
+
+  const logPath = opts.logPath || DEFAULT_LOG_PATH;
+  const entry = {
+    ts: new Date().toISOString(),
+    skillId: event.skillId,
+    source: event.source,
+    ...(event.callerContext ? { callerContext: event.callerContext } : {}),
+  };
+
+  try {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf8');
+  } catch {
+    // Append-only telemetry; if the user's home dir is unwritable we silently
+    // skip rather than break the skill load that triggered us.
+  }
+}
+
+/**
+ * Read every event from a skill-calls log and roll it up into per-skill stats:
+ * load count, distinct sources, most-recent timestamp.
+ */
+export function summarizeSkillCalls({ logPath = DEFAULT_LOG_PATH } = {}) {
+  if (!fs.existsSync(logPath)) return { totalEvents: 0, skills: {} };
+  const lines = fs.readFileSync(logPath, 'utf8').split('\n').filter(Boolean);
+  const skills = {};
+  for (const line of lines) {
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (!entry?.skillId) continue;
+    const slot = skills[entry.skillId] ||= { calls: 0, sources: new Set(), lastCalledAt: null };
+    slot.calls += 1;
+    if (entry.source) slot.sources.add(entry.source);
+    if (entry.ts && (!slot.lastCalledAt || entry.ts > slot.lastCalledAt)) {
+      slot.lastCalledAt = entry.ts;
+    }
+  }
+  const result = {};
+  for (const [id, slot] of Object.entries(skills)) {
+    result[id] = { calls: slot.calls, sources: [...slot.sources].sort(), lastCalledAt: slot.lastCalledAt };
+  }
+  return { totalEvents: lines.length, skills: result };
+}

package/lib/telemetry/team-rollup.mjs

@@ -3,22 +3,22 @@
  *
  * Groups agent traces by teamId (stamped by construct headhunt at overlay creation),
  * computes per-team success rates, latency, handoff counts, and common blockers.
- * Backend is selected via CONSTRUCT_TRACE_BACKEND env var (default: langfuse).
+ * Backend is selected via CONSTRUCT_TRACE_BACKEND env var (default: remote).
  * Called by 'construct team review'.
  */
 
-import * as langfuseBackend from './backends/langfuse.mjs';
+import * as remoteBackend from './backends/remote.mjs';
 import * as noopBackend from './backends/noop.mjs';
 
 const BACKENDS = {
-  langfuse: langfuseBackend,
+  remote: remoteBackend,
   noop: noopBackend,
 };
 
 const DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
 function resolveBackend() {
-  const name = process.env.CONSTRUCT_TRACE_BACKEND ?? 'langfuse';
+  const name = process.env.CONSTRUCT_TRACE_BACKEND ?? 'remote';
   const backend = BACKENDS[name];
   if (!backend) throw new Error(`Unknown trace backend: ${name}. Available: ${Object.keys(BACKENDS).join(', ')}`);
   return backend;

package/lib/token-engine.js

@@ -0,0 +1,117 @@
+/**
+ * lib/token-engine.js — Model-agnostic token estimation engine.
+ *
+ * Follows embeddings-engine.js pattern:
+ *   - This file is the model-agnostic router.
+ *   - Provider-specific logic lives in token-estimator-*.js adapters.
+ *   - All adapters return: { estimate: function(text): number }
+ *
+ * Supported providers:
+ *   - anthropic → ~3.5 chars/token (Claude)
+ *   - openai    → ~4 chars/token (GPT-4o)
+ *   - google    → ~4 chars/token (Gemini)
+ *   - deepseek  → ~3 chars/token
+ *   - default   → ~4 chars/token (conservative)
+ */
+import { resolveProviderCapabilities } from './provider-capabilities.js';
+
+const ADAPTERS = {
+  anthropic: () => import('./token-estimator-anthropic.js'),
+  'anthropic-direct': () => import('./token-estimator-anthropic.js'),
+  openai: () => import('./token-estimator-openai.js'),
+  'openai-direct': () => import('./token-estimator-openai.js'),
+  google: () => import('./token-estimator-google.js'),
+  'google-direct': () => import('./token-estimator-google.js'),
+  deepseek: () => import('./token-estimator-deepseek.js'),
+  default: () => import('./token-estimator-default.js'),
+};
+
+function resolveAdapterKey(modelId) {
+  const id = String(modelId || '').toLowerCase();
+  if (/^anthropic\//.test(id) || /^openrouter\/anthropic\//.test(id)) return 'anthropic';
+  if (/^openai\//.test(id) || /^openrouter\/openai\//.test(id) || /^github-copilot\//.test(id)) return 'openai';
+  if (/^google\//.test(id) || /^openrouter\/google\//.test(id)) return 'google';
+  if (/^deepseek\//.test(id) || /^openrouter\/deepseek\//.test(id)) return 'deepseek';
+  return 'default';
+}
+
+/**
+ * Estimate tokens for a given text and model.
+ * Uses provider-specific ratios when available, falls back to default.
+ *
+ * @param {string} text
+ * @param {object} opts - { modelId: string }
+ * @returns {Promise<number>}
+ */
+export async function estimateTokens(text, { modelId = 'default' } = {}) {
+  const adapterKey = resolveAdapterKey(modelId);
+  const loader = ADAPTERS[adapterKey] || ADAPTERS.default;
+
+  try {
+    const { estimate } = await loader();
+    return estimate(text);
+  } catch {
+    // Fallback to default
+    const { estimate } = await ADAPTERS.default();
+    return estimate(text);
+  }
+}
+
+/**
+ * Synchronous version — uses cached capabilities when possible.
+ * Returns 0 on error.
+ *
+ * @param {string} text
+ * @param {object} opts - { modelId: string }
+ * @returns {number}
+ */
+export function estimateTokensSync(text, { modelId = 'default' } = {}) {
+  try {
+    // Try to get the ratio from provider capabilities (sync)
+    const caps = resolveProviderCapabilitiesSync(modelId);
+    const ratio = caps?.tokenRatio || 4;
+    const len = (text || '').length;
+    return Math.ceil(len / ratio);
+  } catch {
+    // Fallback: 4 chars per token
+    return Math.ceil((text || '').length / 4);
+  }
+}
+
+/**
+ * Estimate tokens for an array of texts.
+ *
+ * @param {string[]} texts
+ * @param {object} opts
+ * @returns {Promise<number[]>}
+ */
+export async function estimateTokensBatch(texts, opts = {}) {
+  return Promise.all((texts || []).map(t => estimateTokens(t, opts)));
+}
+
+/**
+ * Estimate the total tokens for a prompt structure (from composePrompt).
+ *
+ * @param {object} promptStructure - { system, messages, fragments }
+ * @param {object} opts
+ * @returns {Promise<number>}
+ */
+export async function estimatePromptTokens(promptStructure, opts = {}) {
+  const { system, messages, fragments } = promptStructure || {};
+  let total = 0;
+
+  if (system) total += await estimateTokens(system, opts);
+  if (Array.isArray(messages)) {
+    for (const msg of messages) {
+      const content = typeof msg?.content === 'string' ? msg.content : JSON.stringify(msg.content);
+      total += await estimateTokens(content, opts);
+    }
+  }
+  if (Array.isArray(fragments)) {
+    for (const f of fragments) {
+      total += await estimateTokens(f?.content || '', opts);
+    }
+  }
+
+  return total;
+}

package/lib/token-estimator-anthropic.js

@@ -0,0 +1,15 @@
+/**
+ * lib/token-estimator-anthropic.js — Anthropic Claude token estimator.
+ *
+ * Claude models use ~3.5 chars per token (more efficient than GPT).
+ * Uses approximation since we can't load the real tokenizer in Node.
+ */
+export function estimate(text) {
+  // Claude: ~3.5 chars per token
+  const chars = (text || '').length;
+  return Math.ceil(chars / 3.5);
+}
+
+export async function estimateBatch(texts) {
+  return (texts || []).map(t => estimate(t));
+}

package/lib/token-estimator-deepseek.js

@@ -0,0 +1,13 @@
+/**
+ * lib/token-estimator-deepseek.js — DeepSeek token estimator.
+ *
+ * DeepSeek models use ~3 chars per token (similar to Claude).
+ */
+export function estimate(text) {
+  // DeepSeek: ~3 chars per token
+  return Math.ceil((text || '').length / 3);
+}
+
+export async function estimateBatch(texts) {
+  return (texts || []).map(t => estimate(t));
+}

package/lib/token-estimator-default.js

@@ -0,0 +1,13 @@
+/**
+ * lib/token-estimator-default.js — Conservative default token estimator.
+ *
+ * Uses ~4 chars per token (safe for most models).
+ */
+export function estimate(text) {
+  // Conservative default: 4 chars per token
+  return Math.ceil((text || '').length / 4);
+}
+
+export async function estimateBatch(texts) {
+  return (texts || []).map(t => estimate(t));
+}

package/lib/token-estimator-google.js

@@ -0,0 +1,13 @@
+/**
+ * lib/token-estimator-google.js — Google Gemini token estimator.
+ *
+ * Gemini models use ~4 chars per token.
+ */
+export function estimate(text) {
+  // Gemini: ~4 chars per token
+  return Math.ceil((text || '').length / 4);
+}
+
+export async function estimateBatch(texts) {
+  return (texts || []).map(t => estimate(t));
+}

package/lib/token-estimator-openai.js

@@ -0,0 +1,13 @@
+/**
+ * lib/token-estimator-openai.js — OpenAI GPT token estimator.
+ *
+ * GPT models use ~4 chars per token.
+ */
+export function estimate(text) {
+  // GPT: ~4 chars per token
+  return Math.ceil((text || '').length / 4);
+}
+
+export async function estimateBatch(texts) {
+  return (texts || []).map(t => estimate(t));
+}

package/lib/toolkit-env.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/toolkit-env.mjs — Load `.env` from CX_TOOLKIT_DIR into process.env.
  *
- * Shared by OpenCode plugin and MCP server so Langfuse/OpenRouter creds
+ * Shared by OpenCode plugin and MCP server so telemetry/OpenRouter creds
  * reach every host that drives Construct.
  */
 import { existsSync, readFileSync } from "node:fs";

package/lib/tty-prompts.mjs

@@ -0,0 +1,211 @@
+/**
+ * lib/tty-prompts.mjs — terminal UI components for construct CLI.
+ *
+ * Provides menu and multi-select interfaces with keyboard navigation,
+ * rendering, and input handling for interactive prompts.
+ */
+
+import readline, { createInterface } from 'node:readline';
+
+const ESC = '\x1b[';
+const ALT_SCREEN_ON = `${ESC}?1049h`;
+const ALT_SCREEN_OFF = `${ESC}?1049l`;
+const CURSOR_HIDE = `${ESC}?25l`;
+const CURSOR_SHOW = `${ESC}?25h`;
+const HOME_CLEAR = `${ESC}H${ESC}2J`;
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+
+function truncate(text, maxWidth) {
+  if (!text) return '';
+  if (text.length <= maxWidth) return text;
+  return `${text.slice(0, Math.max(0, maxWidth - 1))}...`;
+}
+
+function wrapText(text, width) {
+  if (!text) return [];
+  const words = String(text).split(/\s+/).filter(Boolean);
+  const lines = [];
+  let current = '';
+  for (const word of words) {
+    const next = current ? `${current} ${word}` : word;
+    if (next.length <= width) {
+      current = next;
+      continue;
+    }
+    if (current) lines.push(current);
+    current = word.length > width ? truncate(word, width) : word;
+  }
+  if (current) lines.push(current);
+  return lines;
+}
+
+function renderFrame(content) {
+  return `${HOME_CLEAR}${content}`;
+}
+
+function renderDetailBlock(label, text, width) {
+  const lines = wrapText(text, width);
+  if (!lines.length) return '';
+  return `${BOLD}${label}:${RESET}\n${lines.map((line) => `  ${line}`).join('\n')}\n`;
+}
+
+function createMenuSession(render, onKeypress) {
+  return new Promise((resolve, reject) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true,
+      escapeCodeTimeout: 50,
+    });
+
+    readline.emitKeypressEvents(process.stdin, rl);
+    if (process.stdin.isTTY) process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdout.write(`${ALT_SCREEN_ON}${CURSOR_HIDE}`);
+
+    function redraw() {
+      process.stdout.write(renderFrame(render()));
+    }
+
+    function cleanup() {
+      process.stdin.removeListener('keypress', handleKeypress);
+      if (process.stdin.isTTY) process.stdin.setRawMode(false);
+      rl.close();
+      process.stdin.pause();
+      process.stdout.write(`${CURSOR_SHOW}${ALT_SCREEN_OFF}`);
+    }
+
+    function finish(value) {
+      cleanup();
+      resolve(value);
+    }
+
+    function cancel(error) {
+      cleanup();
+      reject(error);
+    }
+
+    function handleKeypress(_str, key = {}) {
+      try {
+        if (key.ctrl && key.name === 'c') {
+          cancel(new Error('Canceled by user.'));
+          return;
+        }
+        const result = onKeypress(key, { redraw, finish, cancel });
+        if (result !== false) redraw();
+      } catch (error) {
+        cancel(error);
+      }
+    }
+
+    process.stdin.on('keypress', handleKeypress);
+    redraw();
+  });
+}
+
+export async function selectOption({ title, instructions, options, initialIndex = 0 }) {
+  let cursor = Math.min(Math.max(initialIndex, 0), Math.max(0, options.length - 1));
+
+  return createMenuSession(
+    () => {
+      const width = Math.max(60, (process.stdout.columns || 80) - 4);
+      const focused = options[cursor] ?? options[0];
+      const lines = [
+        `${BOLD}${title}${RESET}`,
+        `${DIM}${instructions}${RESET}`,
+        '',
+      ];
+
+      for (let index = 0; index < options.length; index += 1) {
+        const option = options[index];
+        const prefix = index === cursor ? `${CYAN}>${RESET}` : ' ';
+        const label = index === cursor ? `${BOLD}${option.label}${RESET}` : option.label;
+        const meta = option.meta ? `  ${DIM}${truncate(option.meta, 24)}${RESET}` : '';
+        lines.push(` ${prefix} ${label}${meta}`);
+      }
+
+      lines.push('');
+      if (focused) {
+        lines.push(renderDetailBlock('Details', focused.description, width).trimEnd());
+      }
+
+      return `${lines.filter(Boolean).join('\n')}\n`;
+    },
+    (key, controls) => {
+      if (key.name === 'up' || key.name === 'k' || (key.ctrl && key.name === 'p')) {
+        cursor = (cursor - 1 + options.length) % options.length;
+      } else if (key.name === 'down' || key.name === 'j' || (key.ctrl && key.name === 'n')) {
+        cursor = (cursor + 1) % options.length;
+      } else if (key.name === 'return' || key.name === 'enter') {
+        controls.finish(options[cursor]?.value ?? options[cursor]?.label);
+      } else if (key.name === 'escape' || key.name === 'q') {
+        controls.cancel(new Error('Canceled by user.'));
+      }
+    },
+  );
+}
+
+export async function multiSelect({ title, instructions, options }) {
+  const state = options.map((option) => ({ ...option }));
+  let cursor = 0;
+
+  return createMenuSession(
+    () => {
+      const width = Math.max(60, (process.stdout.columns || 80) - 4);
+      const focused = state[cursor] ?? state[0];
+      const selected = state.filter((option) => option.checked).map((option) => option.label);
+      const lines = [
+        `${BOLD}${title}${RESET}`,
+        `${DIM}${instructions}${RESET}`,
+        '',
+      ];
+
+      for (let index = 0; index < state.length; index += 1) {
+        const option = state[index];
+        const prefix = index === cursor ? `${CYAN}>${RESET}` : ' ';
+        const box = option.checked ? '[x]' : '[ ]';
+        const label = index === cursor ? `${BOLD}${option.label}${RESET}` : option.label;
+        const meta = option.meta ? `  ${DIM}${truncate(option.meta, 18)}${RESET}` : '';
+        const marker = option.suggestion ? `  ${YELLOW}*${RESET}` : '';
+        lines.push(` ${prefix} ${box} ${label}${meta}${marker}`);
+      }
+
+      lines.push('');
+      if (focused) {
+        lines.push(renderDetailBlock('Details', focused.description, width).trimEnd());
+        if (focused.suggestion) {
+          lines.push('');
+          lines.push(renderDetailBlock('Suggested because', focused.suggestion, width).trimEnd());
+        }
+      }
+      lines.push('');
+      lines.push(renderDetailBlock('Selected', selected.length ? selected.join(', ') : 'None yet.', width).trimEnd());
+      lines.push('');
+      lines.push(`${DIM}↑↓ Navigate • Space Toggle • Enter Confirm • A Select All • I Invert • Q Cancel${RESET}`);
+
+      return `${lines.filter(Boolean).join('\n')}\n`;
+    },
+    (key, controls) => {
+      if (key.name === 'up' || key.name === 'k' || (key.ctrl && key.name === 'p')) {
+        cursor = (cursor - 1 + state.length) % state.length;
+      } else if (key.name === 'down' || key.name === 'j' || (key.ctrl && key.name === 'n')) {
+        cursor = (cursor + 1) % state.length;
+      } else if (key.name === 'space') {
+        state[cursor].checked = !state[cursor].checked;
+      } else if (key.name === 'a') {
+        const allChecked = state.every((option) => option.checked);
+        state.forEach((option) => { option.checked = !allChecked; });
+      } else if (key.name === 'i') {
+        state.forEach((option) => { option.checked = !option.checked; });
+      } else if (key.name === 'return' || key.name === 'enter') {
+        controls.finish(state.filter((option) => option.checked).map((option) => option.value ?? option.label));
+      } else if (key.name === 'escape' || key.name === 'q') {
+        controls.cancel(new Error('Canceled by user.'));
+      }
+    },
+  );
+}