chainlesschain 0.162.189 → 0.162.197

package/src/repl/repl-keybindings.js

@@ -0,0 +1,227 @@
+/** Declarative, validated keybindings for interactive prompt actions. */
+
+export const REPL_KEYBINDING_ACTIONS = Object.freeze([
+  "prompt.edit",
+  "prompt.stash",
+  "prompt.pop",
+  "session.recap",
+  "suggestions.toggle",
+]);
+
+export const DEFAULT_REPL_KEYBINDINGS = Object.freeze({
+  "prompt.edit": Object.freeze(["ctrl+g"]),
+  "prompt.stash": Object.freeze(["alt+s"]),
+  "prompt.pop": Object.freeze(["alt+p"]),
+  "session.recap": Object.freeze(["alt+r"]),
+  "suggestions.toggle": Object.freeze(["alt+n"]),
+});
+
+const MODIFIER_ORDER = ["ctrl", "alt", "shift"];
+const MODIFIER_ALIASES = new Map([
+  ["control", "ctrl"],
+  ["option", "alt"],
+  // Node's terminal keypress API reports an escape-prefixed Alt/Option key as
+  // `meta`; desktop Command/Windows keys are not reliably exposed to readline.
+  ["meta", "alt"],
+]);
+const KEY_ALIASES = new Map([
+  ["return", "enter"],
+  ["esc", "escape"],
+  ["spacebar", "space"],
+]);
+const SAFE_NAMED_KEYS = new Set([
+  "backspace",
+  "delete",
+  "down",
+  "end",
+  "enter",
+  "escape",
+  "home",
+  "insert",
+  "left",
+  "pageup",
+  "pagedown",
+  "right",
+  "space",
+  "tab",
+  "up",
+]);
+const RESERVED_CHORDS = new Set([
+  "ctrl+c",
+  "ctrl+d",
+  "ctrl+q",
+  "ctrl+s",
+  "ctrl+z",
+  "enter",
+  "escape",
+  "shift+tab",
+  "tab",
+]);
+
+export const REPL_KEYBINDINGS_JSON_SCHEMA = Object.freeze({
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  additionalProperties: false,
+  properties: Object.fromEntries(
+    REPL_KEYBINDING_ACTIONS.map((action) => [
+      action,
+      {
+        oneOf: [
+          { type: "string", minLength: 1 },
+          {
+            type: "array",
+            items: { type: "string", minLength: 1 },
+            uniqueItems: true,
+          },
+          { type: "null" },
+        ],
+      },
+    ]),
+  ),
+});
+
+export function normalizeKeyChord(value) {
+  const raw = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!raw) throw new Error("key chord is empty");
+  const parts = raw.split("+").map((part) => part.trim());
+  if (parts.some((part) => !part)) throw new Error(`invalid key chord: ${raw}`);
+  const modifiers = new Set();
+  let key = null;
+  for (const rawPart of parts) {
+    const part = MODIFIER_ALIASES.get(rawPart) || rawPart;
+    if (MODIFIER_ORDER.includes(part)) {
+      if (modifiers.has(part)) throw new Error(`duplicate modifier: ${part}`);
+      modifiers.add(part);
+      continue;
+    }
+    if (key !== null) throw new Error(`key chord has multiple keys: ${raw}`);
+    key = KEY_ALIASES.get(part) || part;
+  }
+  if (!key) throw new Error(`key chord has no key: ${raw}`);
+  if (!/^[a-z0-9]$/.test(key) && !/^f(?:[1-9]|1[0-2])$/.test(key)) {
+    if (!SAFE_NAMED_KEYS.has(key)) throw new Error(`unsupported key: ${key}`);
+  }
+  const chord = [
+    ...MODIFIER_ORDER.filter((modifier) => modifiers.has(modifier)),
+    key,
+  ].join("+");
+  if (RESERVED_CHORDS.has(chord)) {
+    throw new Error(`reserved terminal key chord: ${chord}`);
+  }
+  return chord;
+}
+
+function configuredKeybindings(settings = {}) {
+  if (settings.cli?.keybindings != null) return settings.cli.keybindings;
+  if (settings.keybindings != null) return settings.keybindings;
+  if (
+    settings &&
+    typeof settings === "object" &&
+    Object.keys(settings).some((key) => REPL_KEYBINDING_ACTIONS.includes(key))
+  ) {
+    return settings;
+  }
+  return {};
+}
+
+/**
+ * Compile settings to a chord -> action map. An explicit null/[] disables the
+ * default for that action. Invalid entries are reported and never installed.
+ */
+export function validateReplKeybindings(settings = {}, options = {}) {
+  const configured = configuredKeybindings(settings);
+  const errors = [];
+  const actionBindings = {};
+  const includeDefaults = options.includeDefaults !== false;
+
+  if (
+    !configured ||
+    typeof configured !== "object" ||
+    Array.isArray(configured)
+  ) {
+    return {
+      valid: false,
+      errors: ["keybindings must be an object"],
+      bindings: new Map(),
+      actionBindings,
+    };
+  }
+  for (const key of Object.keys(configured)) {
+    if (!REPL_KEYBINDING_ACTIONS.includes(key)) {
+      errors.push(`unknown keybinding action: ${key}`);
+    }
+  }
+
+  const chordOwners = new Map();
+  for (const action of REPL_KEYBINDING_ACTIONS) {
+    const hasOverride = Object.prototype.hasOwnProperty.call(
+      configured,
+      action,
+    );
+    const raw = hasOverride
+      ? configured[action]
+      : includeDefaults
+        ? DEFAULT_REPL_KEYBINDINGS[action]
+        : [];
+    const values = raw == null ? [] : Array.isArray(raw) ? raw : [raw];
+    actionBindings[action] = [];
+    for (const value of values) {
+      let chord;
+      try {
+        chord = normalizeKeyChord(value);
+      } catch (error) {
+        errors.push(`${action}: ${error.message}`);
+        continue;
+      }
+      const owner = chordOwners.get(chord);
+      if (owner && owner !== action) {
+        errors.push(
+          `key chord ${chord} is assigned to both ${owner} and ${action}`,
+        );
+        continue;
+      }
+      chordOwners.set(chord, action);
+      if (!actionBindings[action].includes(chord)) {
+        actionBindings[action].push(chord);
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    bindings: new Map(
+      [...chordOwners].map(([chord, action]) => [chord, action]),
+    ),
+    actionBindings,
+  };
+}
+
+export function keypressToChord(input, key = {}) {
+  let name = String(key.name || "").toLowerCase();
+  if (!name && typeof input === "string" && [...input].length === 1) {
+    name = input.toLowerCase();
+  }
+  name = KEY_ALIASES.get(name) || name;
+  if (name === " ") name = "space";
+  if (!name) return null;
+  const parts = [];
+  if (key.ctrl) parts.push("ctrl");
+  if (key.meta || key.alt) parts.push("alt");
+  if (key.shift) parts.push("shift");
+  parts.push(name);
+  try {
+    return normalizeKeyChord(parts.join("+"));
+  } catch {
+    return null;
+  }
+}
+
+export function matchReplKeybinding(compiled, input, key) {
+  const bindings =
+    compiled?.bindings instanceof Map ? compiled.bindings : compiled;
+  if (!(bindings instanceof Map)) return null;
+  const chord = keypressToChord(input, key);
+  return chord ? bindings.get(chord) || null : null;
+}

package/src/repl/session-recap.js

@@ -0,0 +1,217 @@
+/**
+ * Lightweight `/recap` support for the interactive agent.
+ *
+ * The recap deliberately reads only the rebuildable session metadata sidecar
+ * and at most the newest matching transcript records through the store's
+ * reverse-reader. It never calls `readEvents()` or rebuilds the whole chat.
+ */
+import {
+  findLatestEvent,
+  getJsonlSessionMetadata,
+  resolveSessionId,
+} from "../harness/jsonl-session-store.js";
+
+const DEFAULT_PREVIEW_CHARS = 180;
+
+function safeLabel(value, maxChars = 200) {
+  return String(value || "")
+    .replace(/[\p{Cc}\p{Cf}]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, maxChars);
+}
+
+function safeIso(value) {
+  const timestamp = Number(value);
+  if (!Number.isFinite(timestamp)) return "";
+  const date = new Date(timestamp);
+  return Number.isNaN(date.getTime()) ? "" : date.toISOString();
+}
+
+function flattenContent(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => {
+      if (typeof part === "string") return part;
+      return typeof part?.text === "string" ? part.text : "";
+    })
+    .join(" ");
+}
+
+export function recapPreview(content, maxChars = DEFAULT_PREVIEW_CHARS) {
+  const normalized = flattenContent(content)
+    .replace(/[\p{Cc}\p{Cf}]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  const limit = Math.max(20, Number(maxChars) || DEFAULT_PREVIEW_CHARS);
+  return normalized.length > limit
+    ? `${normalized.slice(0, Math.max(1, limit - 1))}…`
+    : normalized;
+}
+
+function latestCheckpointTurns(event, previewChars) {
+  const messages = Array.isArray(event?.data?.messages)
+    ? event.data.messages
+    : [];
+  const turns = [];
+  for (
+    let index = messages.length - 1;
+    index >= 0 && turns.length < 2;
+    index--
+  ) {
+    const message = messages[index];
+    if (message?.role !== "user" && message?.role !== "assistant") continue;
+    const preview = recapPreview(message.content, previewChars);
+    if (preview) turns.push({ role: message.role, preview });
+  }
+  return turns.reverse();
+}
+
+function compactDetails(event, previewChars) {
+  if (!event) return null;
+  const data = event.data && typeof event.data === "object" ? event.data : {};
+  const numeric = (value) => {
+    if (value === null || value === undefined || value === "") return null;
+    return Number.isFinite(Number(value)) ? Number(value) : null;
+  };
+  return {
+    timestamp: safeIso(event.timestamp),
+    strategy: typeof data.strategy === "string" ? data.strategy : "",
+    originalMessages: numeric(data.originalMessages),
+    compressedMessages: numeric(data.compressedMessages),
+    savedTokens: numeric(data.saved),
+    summary: recapPreview(data.summary, previewChars),
+    turns: latestCheckpointTurns(event, previewChars),
+  };
+}
+
+function latestTurnDetails(event, previewChars) {
+  if (!event) return null;
+  const role =
+    event.type === "user_message"
+      ? "user"
+      : event.type === "assistant_message"
+        ? "assistant"
+        : "";
+  const preview = recapPreview(event.data?.content, previewChars);
+  if (!role || !preview) return null;
+  return {
+    role,
+    preview,
+    timestamp: safeIso(event.timestamp),
+  };
+}
+
+/**
+ * Build a bounded, provider-neutral recap projection.
+ *
+ * `store` is injectable to make the important no-full-transcript contract
+ * directly testable. The default store methods all use metadata/reverse IO.
+ */
+export function buildSessionRecap(sessionId, options = {}) {
+  const store = {
+    resolveSessionId,
+    getJsonlSessionMetadata,
+    findLatestEvent,
+    ...(options.store || {}),
+  };
+  const previewChars = Math.max(
+    20,
+    Number(options.previewChars) || DEFAULT_PREVIEW_CHARS,
+  );
+  const requestedId = String(sessionId || "").trim();
+  if (!requestedId) {
+    return { found: false, sessionId: "", reason: "session id is required" };
+  }
+
+  const resolvedId = store.resolveSessionId(requestedId);
+  if (!resolvedId) {
+    return {
+      found: false,
+      sessionId: requestedId,
+      reason: `session not found: ${requestedId}`,
+    };
+  }
+  const metadata = store.getJsonlSessionMetadata(resolvedId);
+  if (!metadata) {
+    return {
+      found: false,
+      sessionId: resolvedId,
+      reason: `session metadata unavailable: ${resolvedId}`,
+    };
+  }
+
+  const compact = store.findLatestEvent(resolvedId, "compact");
+  const latestTurn = store.findLatestEvent(resolvedId, [
+    "user_message",
+    "assistant_message",
+  ]);
+  return {
+    found: true,
+    sessionId: safeLabel(resolvedId, 200),
+    title: safeLabel(metadata.title, 200) || "Untitled",
+    provider: safeLabel(metadata.provider, 80),
+    model: safeLabel(metadata.model, 160),
+    messageCount: Math.max(0, Number(metadata.message_count) || 0),
+    createdAt: metadata.created_at || "",
+    updatedAt: metadata.updated_at || "",
+    checkpoint: compactDetails(compact, previewChars),
+    latestTurn: latestTurnDetails(latestTurn, previewChars),
+    source: "session-metadata+reverse-events",
+  };
+}
+
+export function renderSessionRecap(recap) {
+  if (!recap?.found) return recap?.reason || "Session recap unavailable.";
+  const identity = [safeLabel(recap.provider, 80), safeLabel(recap.model, 160)]
+    .filter(Boolean)
+    .join(" / ");
+  const lines = [
+    `Session recap: ${safeLabel(recap.title, 200) || "Untitled"}`,
+    `ID: ${safeLabel(recap.sessionId, 200)}`,
+    `Messages: ${recap.messageCount}`,
+  ];
+  if (identity) lines.push(`Model: ${identity}`);
+  if (recap.updatedAt) lines.push(`Updated: ${safeLabel(recap.updatedAt, 80)}`);
+
+  const checkpoint = recap.checkpoint;
+  if (checkpoint) {
+    const stats = [];
+    if (checkpoint.strategy) stats.push(checkpoint.strategy);
+    if (
+      checkpoint.originalMessages !== null &&
+      checkpoint.compressedMessages !== null
+    ) {
+      stats.push(
+        `${checkpoint.originalMessages} -> ${checkpoint.compressedMessages} messages`,
+      );
+    }
+    if (checkpoint.savedTokens !== null) {
+      stats.push(`${checkpoint.savedTokens} tokens saved`);
+    }
+    lines.push(`Checkpoint: ${stats.join(", ") || "available"}`);
+    if (checkpoint.summary) lines.push(`Summary: ${checkpoint.summary}`);
+    for (const turn of checkpoint.turns) {
+      lines.push(
+        `${turn.role === "user" ? "Checkpoint ask" : "Checkpoint reply"}: ${turn.preview}`,
+      );
+    }
+  } else {
+    lines.push("Checkpoint: none yet");
+  }
+
+  if (
+    recap.latestTurn &&
+    !checkpoint?.turns?.some(
+      (turn) =>
+        turn.role === recap.latestTurn.role &&
+        turn.preview === recap.latestTurn.preview,
+    )
+  ) {
+    lines.push(
+      `${recap.latestTurn.role === "user" ? "Latest ask" : "Latest reply"}: ${recap.latestTurn.preview}`,
+    );
+  }
+  return lines.join("\n");
+}

package/src/repl/slash-command-registry.js

@@ -4,7 +4,7 @@
  */
 
 import { formatBackgroundTasks } from "./tasks-status.js";
-import { runDoctorChecks } from "./doctor-status.js";
+import { buildDoctorChecks, renderDoctor } from "./doctor-status.js";
 
 export class SlashCommandRegistry {
   static _instance = null;
@@ -55,6 +55,28 @@ export class SlashCommandRegistry {
   _registerBuiltinCommands() {
     // All Claude Code parity commands
     const commands = [
+      [
+        "/advisor",
+        "Independent tool-free critic (on|off|once|status)",
+        async (args, { write, advisor, messages }) => {
+          if (!advisor) {
+            write("Advisor runtime is unavailable.");
+            return;
+          }
+          const { parseAdvisorCommand, executeAdvisorCommand } =
+            await import("./advisor-command.js");
+          const suffix = String(args || "").trim();
+          const parsed = parseAdvisorCommand(
+            `/advisor${suffix ? ` ${suffix}` : ""}`,
+          );
+          const result = await executeAdvisorCommand(parsed, {
+            runtime: advisor,
+            messages,
+          });
+          if (result?.guidance) advisor.queueGuidance(result.guidance);
+          write(result?.output || "Advisor command did not run.");
+        },
+      ],
       [
         "/bug",
         "Submit a bug report",
@@ -102,9 +124,8 @@ export class SlashCommandRegistry {
       [
         "/doctor",
         "Check system health",
-        async (args, { write }) => {
-          write("Running system diagnostics...");
-          await runDoctorChecks(write);
+        (args, { write, doctorInput = {} }) => {
+          write(renderDoctor(buildDoctorChecks(doctorInput)));
         },
       ],
       [

package/src/repl/terminal-layout.js

@@ -0,0 +1,88 @@
+/** Unicode-aware, ANSI-free layout helpers for small terminal surfaces. */
+
+const graphemeSegmenter =
+  typeof Intl?.Segmenter === "function"
+    ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+    : null;
+
+function graphemes(value) {
+  const text = String(value ?? "");
+  return graphemeSegmenter
+    ? [...graphemeSegmenter.segment(text)].map((part) => part.segment)
+    : [...text];
+}
+
+function isFullWidthCodePoint(codePoint) {
+  if (!Number.isInteger(codePoint)) return false;
+  return (
+    codePoint >= 0x1100 &&
+    (codePoint <= 0x115f ||
+      codePoint === 0x2329 ||
+      codePoint === 0x232a ||
+      (codePoint >= 0x2e80 && codePoint <= 0x3247 && codePoint !== 0x303f) ||
+      (codePoint >= 0x3250 && codePoint <= 0x4dbf) ||
+      (codePoint >= 0x4e00 && codePoint <= 0xa4c6) ||
+      (codePoint >= 0xa960 && codePoint <= 0xa97c) ||
+      (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+      (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+      (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+      (codePoint >= 0xfe30 && codePoint <= 0xfe6b) ||
+      (codePoint >= 0xff01 && codePoint <= 0xff60) ||
+      (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+      (codePoint >= 0x1b000 && codePoint <= 0x1b2ff) ||
+      (codePoint >= 0x1f200 && codePoint <= 0x1f251) ||
+      (codePoint >= 0x20000 && codePoint <= 0x3fffd))
+  );
+}
+
+export function graphemeDisplayWidth(grapheme) {
+  const value = String(grapheme || "");
+  if (!value || /^[\p{Mark}\p{Cf}\p{Cc}]+$/u.test(value)) return 0;
+  if (/\p{Extended_Pictographic}/u.test(value)) return 2;
+  for (const character of value) {
+    if (isFullWidthCodePoint(character.codePointAt(0))) return 2;
+  }
+  return 1;
+}
+
+export function terminalDisplayWidth(value) {
+  return graphemes(value).reduce(
+    (width, grapheme) => width + graphemeDisplayWidth(grapheme),
+    0,
+  );
+}
+
+/** Hard-wrap by grapheme without reversing RTL logical order. */
+export function wrapTerminalText(value, columns = 80) {
+  const width = Math.max(8, Math.floor(Number(columns) || 80));
+  const output = [];
+  for (const sourceLine of String(value ?? "").split("\n")) {
+    if (!sourceLine) {
+      output.push("");
+      continue;
+    }
+    let line = "";
+    let lineWidth = 0;
+    for (const grapheme of graphemes(sourceLine)) {
+      const nextWidth = graphemeDisplayWidth(grapheme);
+      if (line && lineWidth + nextWidth > width) {
+        output.push(line);
+        line = "";
+        lineWidth = 0;
+      }
+      line += grapheme;
+      lineWidth += nextWidth;
+    }
+    output.push(line);
+  }
+  return output.join("\n");
+}
+
+/** Screen readers prefer stable logical lines; visual terminals hard-wrap. */
+export function layoutTerminalText(
+  value,
+  { columns = 80, screenReader = false } = {},
+) {
+  const text = String(value ?? "").replace(/\r\n?/g, "\n");
+  return screenReader ? text : wrapTerminalText(text, columns);
+}