howtofixcli 0.7.23 → 0.7.25

package/dist/theme.js

@@ -0,0 +1,79 @@
+import { detectCapabilities, getTerminalColorMode, parseColor, styleText } from "@netrodev/hxf-tui";
+/**
+ * Whether the terminal can show 24-bit colour, decided rather than assumed.
+ *
+ * This was `"truecolor"`, hardcoded, and that is wrong wherever the assumption
+ * does not hold: a `screen` session that never set `COLORTERM`, a `linux` console,
+ * an SSH client on an old terminal. The failure is not a crash — it is worse. A
+ * truecolor escape on a 256-colour terminal is not downsampled, it is *ignored*,
+ * so every colour in the interface collapses to the default foreground and the
+ * whole thing reads as one grey wall.
+ *
+ * `detectCapabilities` already knows the cases: it returns `trueColor: false` for
+ * `TERM=screen*` without a `COLORTERM` hint, for `dumb`, and for anything that
+ * does not advertise 24-bit. Reading it means the HUD degrades to the 256-colour
+ * cube instead of going monochrome.
+ *
+ * `NO_COLOR` (https://no-color.org) is honoured explicitly and beats everything
+ * else, because a user who sets it has asked for no colour at all — and it is
+ * also the escape hatch when the result on a particular terminal is unreadable.
+ */
+function resolveColorMode() {
+    const noColor = process.env.NO_COLOR;
+    if (noColor !== undefined && noColor !== "")
+        return "256color";
+    try {
+        return getTerminalColorMode(detectCapabilities());
+    }
+    catch {
+        return "256color";
+    }
+}
+export const MODE = resolveColorMode();
+/** True when the user asked for no colour: read at paint time, not once. */
+function colorDisabled() {
+    const noColor = process.env.NO_COLOR;
+    return noColor !== undefined && noColor !== "";
+}
+export const ink = {
+    text: parseColor("#e6e6e6"),
+    mute: parseColor("#8b8b8b"),
+    dim: parseColor("#5c5c5c"),
+    user: parseColor("#d0d0d0"),
+    accent: parseColor("#c4b5fd"),
+    tool: parseColor("#6ee7b7"),
+    bad: parseColor("#f0a8a4"),
+    warn: parseColor("#e6b15a"),
+    line: parseColor("#3a3a3a"),
+};
+export function paint(text, style) {
+    if (colorDisabled()) {
+        // Keep the attributes that carry meaning without colour — bold and dim still
+        // separate things on a monochrome terminal, and dropping them too would make
+        // the output unreadable rather than plain.
+        const { bold, dim, italic, underline, strikethrough } = style;
+        if (!bold && !dim && !italic && !underline && !strikethrough)
+            return text;
+        return styleText(text, { bold, dim, italic, underline, strikethrough }, MODE);
+    }
+    return styleText(text, style, MODE);
+}
+export function fg(text, color, extra) {
+    return paint(text, { ...extra, fg: color });
+}
+export const mdTheme = {
+    heading: (text) => fg(text, ink.text, { bold: true }),
+    link: (text) => fg(text, ink.accent, { underline: true }),
+    linkUrl: (text) => fg(text, ink.mute),
+    code: (text) => fg(text, ink.text),
+    codeBlock: (text) => fg(text, ink.text),
+    codeBlockBorder: (text) => fg(text, ink.line),
+    quote: (text) => fg(text, ink.mute, { italic: true }),
+    quoteBorder: (text) => fg(text, ink.line),
+    hr: (text) => fg(text, ink.line),
+    listBullet: (text) => fg(text, ink.mute),
+    bold: (text) => fg(text, ink.text, { bold: true }),
+    italic: (text) => fg(text, ink.text, { italic: true }),
+    strikethrough: (text) => fg(text, ink.mute, { strikethrough: true }),
+    underline: (text) => fg(text, ink.text, { underline: true }),
+};

package/dist/thinking.js

@@ -0,0 +1,45 @@
+/** Every level the CLI accepts, lowest first. One list, shared by every caller. */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+/**
+ * The highest level this model actually reaches the provider with, or
+ * `undefined` when it reaches none — the ceiling decides whether the HUD may
+ * light the shimmer, so its three states have to stay distinguishable:
+ *
+ * - **No map** (`thinkingLevelMap` absent, or no model yet): nothing is known
+ *   per level, so take the highest listed level. It is a guess, but the best
+ *   available one, and it becomes exact the moment a provider fills the map in.
+ * - **With a map**: `null` *and* a missing key both mean unsupported — the
+ *   type is `Partial`, so an absent entry is how a level that was never wired
+ *   up appears. A value of `""` is still a value; `null` is the only marker
+ *   of "does not reach the provider".
+ * - **Every value `null`**: the ceiling is `undefined` and the feature is off
+ *   for this model. Falling back to `max` here would announce a top the model
+ *   does not have.
+ */
+export function levelCeiling(model) {
+    const map = model?.thinkingLevelMap;
+    if (map === undefined)
+        return THINKING_LEVELS[THINKING_LEVELS.length - 1];
+    for (let index = THINKING_LEVELS.length - 1; index >= 0; index -= 1) {
+        const value = map[THINKING_LEVELS[index]];
+        if (typeof value === "string")
+            return THINKING_LEVELS[index];
+    }
+    return undefined;
+}
+/**
+ * One step up, wrapping from the top of the list back to `off`.
+ *
+ * The wrap runs over the whole list, not over the model's ceiling: the SDK
+ * clamps whatever the model rejects, and a wrap that stopped at the ceiling
+ * would leave the raise key dead exactly where the user keeps pressing it.
+ */
+export function nextLevel(level) {
+    const index = THINKING_LEVELS.indexOf(level);
+    return THINKING_LEVELS[(index + 1 + THINKING_LEVELS.length) % THINKING_LEVELS.length];
+}
+/** One step down, wrapping from `off` back to the top of the list. */
+export function prevLevel(level) {
+    const index = THINKING_LEVELS.indexOf(level);
+    return THINKING_LEVELS[(index - 1 + THINKING_LEVELS.length) % THINKING_LEVELS.length];
+}

package/dist/todo.js

@@ -0,0 +1,114 @@
+/**
+ * A session-scoped task list.
+ *
+ * Adapted from the SDK's own `examples/extensions/todo.ts`, which establishes the
+ * pattern that matters: the authoritative state lives in each tool result's
+ * `details`, and the in-memory copy is rebuilt by replaying the current session
+ * branch. Nothing is written to disk, so the list is automatically correct after
+ * a fork, a rewind or a resumed session — an external todo file would silently
+ * disagree with the transcript.
+ *
+ * The op model (`init`/`start`/`done`/`drop`/`view`) is the `todo`
+ * tool (`docs/tools/todo.md`), which is what makes a long run legible: the model
+ * records the whole plan up front, then moves one task at a time, and a stalled
+ * run leaves visible evidence of where it stopped.
+ */
+import { StringEnum } from "@netrodev/hxf-ai";
+import { defineTool } from "@netrodev/hxf-coding-agent";
+import { Type } from "typebox";
+/** Marks the status glyph. All are non-emoji (see scripts/check-tool-render.mjs). */
+const MARK = {
+    pending: "[ ]",
+    in_progress: "[>]",
+    completed: "[x]",
+    dropped: "[-]",
+};
+export const todoParams = Type.Object({
+    op: StringEnum(["init", "start", "done", "drop", "view"], {
+        description: "init replaces the list; start/done/drop move one task; view reads it",
+    }),
+    items: Type.Optional(Type.Array(Type.String(), {
+        description: "Task labels for init. 5-10 words each, specific enough to execute without re-planning",
+    })),
+    task: Type.Optional(Type.String({ description: "Exact label of the task to start, complete or drop" })),
+});
+/** Render the list the way the model should read it back. */
+export function formatTodos(todos) {
+    if (todos.length === 0)
+        return "Todo list is empty.";
+    const done = todos.filter((item) => item.status === "completed").length;
+    const lines = todos.map((item) => `${MARK[item.status]} ${item.content}`);
+    const open = todos.filter((item) => item.status === "pending" || item.status === "in_progress").length;
+    return [`${done}/${todos.length} done, ${open} open`, ...lines].join("\n");
+}
+/**
+ * Apply one op to a list. Pure, so the policy is testable without a session:
+ * `start` demotes any other in-progress task (only one task
+ * is ever in progress).
+ */
+export function applyOp(todos, op, items, task) {
+    const list = todos.map((item) => ({ ...item }));
+    switch (op) {
+        case "init": {
+            if (!items || items.length === 0)
+                return { todos: list, error: "init needs a non-empty items array" };
+            return { todos: items.map((content) => ({ content, status: "pending" })) };
+        }
+        case "view":
+            return { todos: list };
+        case "start":
+        case "done":
+        case "drop": {
+            if (!task)
+                return { todos: list, error: `${op} needs task` };
+            const target = list.find((item) => item.content === task);
+            if (!target)
+                return { todos: list, error: `no task matches ${JSON.stringify(task)}` };
+            if (op === "start") {
+                for (const item of list)
+                    if (item.status === "in_progress")
+                        item.status = "pending";
+                target.status = "in_progress";
+            }
+            else {
+                target.status = op === "done" ? "completed" : "dropped";
+            }
+            return { todos: list };
+        }
+        default:
+            return { todos: list, error: `unknown op ${JSON.stringify(op)}` };
+    }
+}
+/** Rebuild the list by replaying this branch's todo results in order. */
+export function readTodos(ctx) {
+    let todos = [];
+    for (const entry of ctx.sessionManager.getBranch()) {
+        if (entry.type !== "message")
+            continue;
+        const message = entry.message;
+        if (message.role !== "toolResult" || message.toolName !== "todo")
+            continue;
+        const details = message.details;
+        if (details?.todos)
+            todos = details.todos;
+    }
+    return todos;
+}
+export const todoTool = defineTool({
+    name: "todo",
+    label: "todo",
+    description: "Track the plan for this task. Use `init` once with the whole plan (investigation through verification), then `start`/`done` as you go. Keep the list current so progress stays visible; do not re-init unless the plan materially changes.",
+    promptSnippet: "todo: record and advance the plan for the current task",
+    parameters: todoParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        const before = readTodos(ctx);
+        const { todos, error } = applyOp(before, params.op, params.items, params.task);
+        const details = { op: params.op, todos, ...(error ? { error } : {}) };
+        const summary = error ? `Error: ${error}\n${formatTodos(todos)}` : formatTodos(todos);
+        return {
+            content: [{ type: "text", text: summary }],
+            details,
+            ...(error ? { isError: true } : {}),
+        };
+    },
+});

package/dist/tool-loadout.js

@@ -0,0 +1,102 @@
+/**
+ * Keeps this product's tool loadout in place without starving extension tools.
+ *
+ * The SDK's active set starts as `read, bash, edit, write` when `defaultTools`
+ * is unset. The harness now defaults to `grep`, `find` and `ls` as well, so this
+ * pass is what keeps the product's own loadout stable rather than the only thing
+ * that makes those three callable; `bash_output` and `kill_shell` are still
+ * outside the default set and are the pair this exists for.
+ *
+ * `grep`, `find` and `ls` were once registered by the SDK but not active, so
+ * without naming them they were dead weight: `permissions.ts` carried approval
+ * tiers for them and `agents.ts` told every subagent to use them, while the model
+ * could not call them. Measured before that fix: the model reported
+ * `read, bash, edit, write, task, …` and answered "NO GREP TOOL".
+ *
+ * **Where this has to happen.** Not in an extension. An extension's
+ * `session_start` handler runs inside `AgentSession.bindExtensions()`, which the
+ * SDK immediately follows with `_refreshToolRegistry()` — so anything
+ * `setActiveTools` did there is silently overwritten before the first turn.
+ * Measured: the handler ran, `setActiveTools` was called, and the active set was
+ * still `bash, edit, read, write`. `activateExtraBuiltins` is called from
+ * `openSession` instead, on the session object, once the session exists.
+ *
+ * **Why not the SDK's `tools:` option.** It is an allowlist applied to *every*
+ * registered tool — extension tools included — in `_refreshToolRegistry` via
+ * `_isAllowedTool`. Two things break because of that:
+ *
+ * 1. `mcp__<server>__<tool>` names are not knowable in advance, so an allowlist
+ *    discards them. Measured: an MCP server connected, `/mcp` reported "14
+ *    tools", and the model could call none of them.
+ * 2. The MCP extension activates `codemode` at `session_start` for the default
+ *    `exposure: "codemode"`, but the allowlist filter runs when the registry is
+ *    rebuilt — after that activation — so a static list undid it, and the user
+ *    was told "MCP tools are only reachable from the codemode or tool_search
+ *    tool, but neither is active" on a fully connected server.
+ *
+ * Adding to the active set leaves everything the extensions registered exactly
+ * where it was.
+ */
+/**
+ * The built-ins this product offers that the SDK does not enable by default.
+ *
+ * `grep`/`find`/`ls` are registered by the SDK but absent from
+ * `DEFAULT_TOOL_NAMES` (`read, bash, edit, write`), so without naming them they
+ * are dead weight: they have approval tiers and every subagent is told to use
+ * them, while the main agent cannot call them.
+ */
+export const EXTRA_BUILTINS = ["grep", "find", "ls", "bash_output", "kill_shell"];
+/**
+ * Wait, briefly, for extension-registered tools to appear.
+ *
+ * `session_start` handlers are async and the extension runner does not await them
+ * (`ExtensionRunner.emit` starts them and returns), so a handler that registers a
+ * tool — the MCP extension's `codemode` — lands some milliseconds after
+ * `bindExtensions()` resolves. Reading the loadout immediately would report a set
+ * that is about to grow, and the first turn would run without those tools.
+ *
+ * Bounded on purpose: it returns as soon as the set stops growing for a couple of
+ * ticks, and never waits longer than `timeoutMs` however slow a server is. A slow
+ * MCP server therefore cannot delay startup.
+ */
+export async function settleExtensionTools(session, { timeoutMs = 2_000, quietTicks = 2 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    let size = session.getActiveToolNames().length;
+    let quiet = 0;
+    while (Date.now() < deadline && quiet < quietTicks) {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        const next = session.getActiveToolNames().length;
+        if (next > size) {
+            size = next;
+            quiet = 0;
+        }
+        else {
+            quiet += 1;
+        }
+    }
+}
+/**
+ * Add the extra built-ins to a session's active set.
+ *
+ * Only a tool that actually exists is added: `powershell` is registered on every
+ * platform but throws off Windows, and a name that was never registered would
+ * simply be ignored. Adding, never replacing, is what keeps `codemode` and the
+ * MCP tools the MCP extension activated.
+ *
+ * Returns the names that were added, so a caller (or a test) can see what
+ * happened instead of guessing.
+ */
+export function activateExtraBuiltins(session) {
+    const active = new Set(session.getActiveToolNames());
+    const registered = new Set(session.getAllTools().map((tool) => tool.name));
+    const added = [];
+    for (const name of EXTRA_BUILTINS) {
+        if (registered.has(name) && !active.has(name)) {
+            active.add(name);
+            added.push(name);
+        }
+    }
+    if (added.length > 0)
+        session.setActiveToolsByName([...active]);
+    return added;
+}