howtofixcli 0.7.8 → 0.7.9

package/dist/brand-extension.js

@@ -1,87 +0,0 @@
-/**
- * Replace the harness's self-description while keeping every operational part of
- * the prompt (tools, rules, doc paths) intact. Exported for the check script.
- *
- * The rules match the SDK's own wording, which is `hxf` throughout. They used to
- */
-export function scrubHarnessIdentity(prompt) {
-    const scrubbed = prompt
-        // "You are an expert coding assistant operating inside hxf, a coding agent harness."
-        .replace(/operating inside hxf, a coding agent harness/gi, "operating as HowToFix, a coding agent harness")
-        // The docs block header names the harness and invites questions about "hxf itself".
-        // The line ends with "):" — the trailing colon is why an earlier `\)$` pattern missed it.
-        .replace(/^HowToFix documentation \(read only when the user asks about[^\n]*\):?$/gim, "Harness documentation (internal reference; the user is never told the harness name):")
-        .replace(/\bhxf itself\b/gi, "the harness itself")
-        // The bullets inside the docs block.
-        .replace(/^- When reading hxf docs or examples/m, "- When reading harness docs or examples")
-        .replace(/^- When working on hxf topics/m, "- When working on harness topics")
-        .replace(/^- Always read hxf \.md files/m, "- Always read the harness .md files")
-        // Doc topic list: "adding models (docs/models.md), hxf packages (docs/packages.md)".
-        .replace(/\bhxf packages\b/gi, "harness packages")
-        .replace(/\bhxf \.md files\b/gi, "harness .md files")
-        .replace(/\bhxf docs\b/gi, "harness docs")
-        // "You can inspect HXF_* environment variables for current model and session details."
-        .replace(/^-\s*You can inspect HXF_\* environment variables/m, "- You can inspect the harness's environment variables");
-    return scrubbed;
-}
-/**
- * Sections the harness generates itself, and therefore the only ones this may
- * rewrite. `project_context` is the user's own AGENTS.md and `cwd`/`tools` carry
- * no identity framing, so they are left exactly as they are.
- */
-const SCRUBBED_SECTIONS = ["preamble", "rules", "docs", "addendum"];
-/**
- * Scrub the harness-generated sections of a system message, or `undefined` when
- * nothing changed.
- */
-export function scrubSections(sections) {
-    if (!sections)
-        return undefined;
-    let changed = false;
-    const next = { ...sections };
-    for (const name of SCRUBBED_SECTIONS) {
-        const text = next[name];
-        if (typeof text !== "string")
-            continue;
-        const scrubbed = scrubHarnessIdentity(text);
-        if (scrubbed !== text) {
-            next[name] = scrubbed;
-            changed = true;
-        }
-    }
-    return changed ? next : undefined;
-}
-/**
- * Rewrites the harness identity out of the system message on every request.
- *
- * Two details of the SDK shape this, and both cost a debugging round to find:
- *
- * - The prompt is not in `content`. It is rendered from `sections`
- *   (`preamble`, `tools`, `rules`, `docs`, `addendum`, `project_context`, `cwd`),
- *   and `content` holds only extra text prepended to them. A handler that reads
- *   and rewrites `content` therefore sees an empty string and silently does
- *   nothing — which is exactly what the first version of this extension did.
- * - `before_agent_start` is the wrong event. It fires once per run and its
- *   forced prompt is projected onto the request afterwards, overwriting any
- *   edit made to the system message by a later handler. The shared notes
- *   injected by `context-extension.ts` never reached the model until both
- *   extensions moved to `context_with_system`, which runs before every LLM call
- *   and may return a replacement transcript.
- *
- * The returned transcript keeps the leading system message at index 0, which is
- * where the provider reads the prompt and the tool declarations from.
- */
-export function createBrandExtension() {
-    return (hxf) => {
-        hxf.on("context_with_system", async (event) => {
-            const head = event.messages[0];
-            if (!head || head.role !== "system")
-                return undefined;
-            const sections = scrubSections(head.sections);
-            if (!sections)
-                return undefined;
-            const messages = event.messages.map((message) => (message === head ? { ...head, sections: sections } : message));
-            return { messages };
-        });
-    };
-}

package/dist/brand.js

@@ -1,76 +0,0 @@
-export const APP_TITLE = "HowToFix";
-export const APP_VERSION = "0.7.8";
-export const SYSTEM_APPEND = [
-    // House style: RFC 2119 keywords in caps, one claim per line, the
-    // highest-stakes rules at
-    // BOTH edges because the middle of a long prompt degrades, and a positive
-    // alternative wherever a rule is a negation.
-    //
-    // Front matter: role, then the rule whose violation cost the most.
-    "You are HowToFix, a coding agent. The user wants the fix, not a tour of the problem.",
-    'NEVER report a check you did not run. NEVER state a version, path, result or capability you have not verified — if you did not check it, say you are unsure. "Not found" is not "impossible": a tool missing from PATH is often installed anyway, and one that is truly absent can usually be installed. Exhaust the real options before calling anything unavailable; when you do report a limit, say plainly what you tried and what you could not do. Unexercised behaviour is not evidence.',
-    "NEVER mention the underlying harness, its vendor or its project name to the user.",
-    // Permission model. Without this the prompt said nothing about tiers while the
-    // gate enforced them, so the model proposed work it would then be refused. The
-    // mode names, the tier names and the critical-command policy are asserted
-    // against `permissions.ts` by `check-prompt-permissions.mjs`; reword this text
-    // freely, but keep those words or the gate fails.
-    "Every tool is `read`, `write` or `exec`, and each approval mode auto-approves every tier up to its own: `suggest` runs `read` only, `auto-edit` adds `write`, `full-auto` adds `exec`. A read-only shell command runs in every mode, so inspecting the tree asks nothing.",
-    "NEVER aim a command at the filesystem root, a block device or a system account file, and NEVER shut down the host: those are refused in EVERY mode, `full-auto` included, so proposing one wastes the turn. This is not a list of things to avoid — it is a list of things that will not run.",
-    // Middle: how the work is done.
-    "Lead with the diagnosis in one or two sentences, then change the code. SHOULD prefer the smallest correct change over a rewrite. Name the file and the reason in a short line; do not narrate tool calls.",
-    "Fix the problem that was asked for. NEVER add features, refactors, validation, error handling or dependencies nobody requested.",
-    "Something reported broken: reproduce it first, confirm the fix after. Cannot reproduce it? Say so — NEVER edit code and call it fixed.",
-    "Tests describe intended behaviour. A failing test means fix the code, not the test: NEVER delete, skip or loosen an assertion to get green, and NEVER re-pin an expected value to whatever the code happens to print.",
-    "Anything you cannot settle by reading — a page, a layout, a screenshot, a CLI, a service, a failure — run it and look at the result. For a visual task, find a browser the way a real one does: `$PUPPETEER_EXECUTABLE_PATH`, `$CHROME_PATH`, then `which` for google-chrome, chromium and chromium-browser, then /usr/bin, /snap/bin and /var/lib/flatpak, then the puppeteer and playwright caches under the home directory. Still empty? `npx -y puppeteer browsers install chrome`, or `npm i puppeteer-core` against a chrome the image already ships outside PATH. Then drive the real artifact — open it, read the DOM, click the controls, measure at the widths that matter — instead of describing what you assume it does.",
-    "Done means the requested behaviour works end to end and every stated requirement is met — not a scaffold, a narrowed test or a plausible subset. Genuinely out of reach? Finish everything else, then say exactly what is missing and what you tried.",
-    // Working method. Each rule names the tool that implements it, because a
-    // capability the prompt does not mention is one the model reaches for late or
-    // not at all — the tool exists, has a snippet and an approval tier, and still
-    // goes unused. The tool names are asserted against MAIN_TOOLS by
-    // `check-prompt-tools.mjs`, so a rename or a typo fails the gate.
-    "SHOULD plan multi-step work with `todo` before starting it, and mark each step done as you finish. A plan the user can see is worth more than a narration of what you are about to do.",
-    "Genuinely ambiguous design: enter plan mode, write the plan to the plan file, then present it with `exit_plan_mode`. Use it when several reasonable approaches exist or when a restructuring would be hard to undo. In plan mode `edit` and `write` are refused for every path except the plan file itself — that limit is enforced, not advisory, so plan the work rather than starting it. Plan mode needs an interactive session in which the user can approve it; when there is no UI it is unavailable, so design the approach yourself instead of calling it.",
-    "Work that is independent and would flood this conversation belongs in `task` subagents. Give each a self-contained assignment, then verify the file it wrote rather than trusting its summary. When that work has a shape you can script — many items through the same stages, or fan-out whose results must be combined — `workflow` states the orchestration in one place and runs it deterministically; `task` is for the one-off you cannot describe in advance.",
-    "MUST give each subagent a self-contained assignment: a child starts with none of this conversation, so a brief that says 'the file we discussed' reaches it as nothing. Choose the agent by what the work is — scout looks something up, architect returns a plan, reviewer reports issues with file evidence, task changes files — and NEVER send work that needs an edit to scout or reviewer, because neither can make one.",
-    "SHOULD delegate only work that is genuinely parallel: a subagent costs its own session and its own requests on the same quota as this conversation. A single lookup, a file you can read yourself, or a step whose result decides the next step stays here. MUST keep one call to at most six agents and the session to twelve live or parked ones — a larger fan-out is refused, and the refusal is a limit rather than a failure to work around.",
-    "Record a decision, a file's role, or a fact you would otherwise re-derive with `context`: notes survive compaction and are visible to the other agents on the task.",
-    "Look it up instead of recalling it: `web_search` and `web_fetch` for anything outside this repo, `lsp` for a definition, reference or diagnostic. Name the source you checked.",
-    "Before calling changed code done, run `quality` and `slop` over it and act on what they report. A metric you did not measure is a claim you cannot make.",
-    // Every command runs under a 2-minute default timeout, so a slow command is
-    // killed rather than hanging the turn. Observed on Windows: a recursive `du -sh`
-    // over a profile directory takes minutes, and the model has to ask for the time
-    // it needs instead of losing the command to the default.
-    "A command runs under a two-minute default timeout. MUST pass a longer timeout for anything that legitimately takes more than that — a recursive directory walk, a package install, a build, a network fetch — and SHOULD prefer a bounded command to an unbounded one: 'du -sh' with an explicit path beats the whole profile, and on Windows/MSYS a recursive 'du' over a profile directory takes minutes rather than seconds.",
-    "When a choice blocks the task, use `ask` instead of guessing; when you need to work something out, use `think`, whose text stays out of the transcript.",
-    // Back matter: the two that matter most, compressed, because the edge is what
-    // survives a long prompt.
-    "Above all: NEVER claim a check you did not run, and NEVER call done on a subset.",
-].join("\n");
-/**
- * Strip the harness's own identity out of a user-facing message the SDK wrote.
- *
- * `createAgentSession` returns `modelFallbackMessage`, and when no model is
- * configured that string is the SDK's own auth guidance: it names the harness,
- * points at `hxf-coding-agent/docs/providers.md` and `models.md` under the
- * installed package, and tells the user to run `/login` — none of which is our
- * product's copy. The system prompt is scrubbed by `brand-extension.ts`; this is
- * the other surface the user actually reads, and it leaked verbatim.
- *
- * Exported for the check script.
- */
-export function scrubHarnessMessage(message) {
-    if (message === undefined)
-        return undefined;
-    const scrubbed = message
-        // "Use /login to log into a provider via OAuth or API key. See:"
-        .replace(/Use \/login to log into a provider[^\n]*/gi, "Connect a provider with /connect or /login:")
-        // The two doc paths under the installed package. They are the harness's
-        // docs, not ours, and printing the path also prints its name.
-        .replace(/^[ \t]*\S*hxf-coding-agent[\\/]docs[\\/][^\n]*$/gim, "")
-        // Any remaining bare mention.
-        .replace(/\bhxf-coding-agent\b/gi, "the harness");
-    return scrubbed.replace(/\n{3,}/g, "\n\n").trim();
-}
-/** Seed for /init. Written to AGENTS.md when a project has no context file yet. */
-export const INIT_TEMPLATE = ["# Project notes", "", "## What this is", "", "## Commands", "- build:", "- test:", "", "## Conventions", "-", ""].join("\n");

package/dist/browser.js

@@ -1,58 +0,0 @@
-/**
- * Opening a URL in the user's browser.
- *
- * Used by `/connect`, which needs the user to make a token on the gateway's
- * Console. Finding that page is the step people get stuck on, and it is one
- * click to remove.
- *
- * This is a convenience, never a requirement: the caller always prints the URL
- * as well. A headless box, a container, or a missing `xdg-open` must not turn
- * "open the browser" into an error the user has to deal with — the command
- * continues and the URL is on screen either way. So every failure here is
- * swallowed and reported as `false`.
- */
-import { spawn } from "node:child_process";
-/** The platform's way to hand a URL to the default browser, if it has one. */
-export function openerFor(platform) {
-    switch (platform) {
-        case "darwin":
-            return { command: "open", args: [] };
-        case "win32":
-            // `start` is a cmd builtin; the empty argument is the window title, which
-            // is otherwise eaten as the URL.
-            return { command: "cmd", args: ["/c", "start", ""] };
-        case "linux":
-            return { command: "xdg-open", args: [] };
-        default:
-            return undefined;
-    }
-}
-/**
- * Try to open `url` in the browser. Resolves to whether a launcher was started;
- * it does not wait for the browser, and it never rejects.
- */
-export async function openInBrowser(url, platform = process.platform) {
-    const opener = openerFor(platform);
-    if (!opener)
-        return false;
-    return new Promise((resolve) => {
-        try {
-            const child = spawn(opener.command, [...opener.args, url], {
-                // Detached so a long-lived browser is not tied to this process, and
-                // silenced so a missing launcher cannot print over the workbench.
-                detached: true,
-                stdio: "ignore",
-            });
-            child.once("error", () => resolve(false));
-            // "spawn" means the launcher started; whether it found a browser is its
-            // business, and not something this process should block on.
-            child.once("spawn", () => {
-                child.unref();
-                resolve(true);
-            });
-        }
-        catch {
-            resolve(false);
-        }
-    });
-}

package/dist/cache-report.js

@@ -1,139 +0,0 @@
-/**
- * Prompt-cache accounting: how much of what we sent was actually re-sent.
- *
- * Every turn re-sends the whole conversation. A prompt cache is what makes that
- * affordable: the provider recognises the unchanged prefix and bills it at a fraction of
- * the input price. A cache hit rate is therefore not a curiosity — it is the difference
- * between paying once for context and paying for it again on every turn.
- *
- * A high `cacheRead` on its own proves nothing. A session can read a great deal from
- * cache and still re-bill a great deal beside it, and the totals look healthy while the
- * bill does not. The number that matters is the *rate*: of all the prompt tokens we were
- * billed for, what share came from cache.
- *
- * A miss is worth reporting because it is almost always attributable. Two causes
- * dominate, and both are visible in the data: the cache expired during an idle gap, or
- * the model changed and the new one has no cache for that prefix. Naming the likely
- * cause is the difference between a number and something a user can act on.
- */
-/**
- * An idle gap longer than this is worth naming as the likely cause of a miss. Five
- * minutes is the common provider default cache TTL; a gap past it is the explanation,
- * and a shorter one means something else changed.
- */
-export const CACHE_TTL_MS = 5 * 60 * 1000;
-/**
- * A turn with fewer prompt tokens than this is not counted as a miss. Short prompts are
- * often too small to be worth caching at all, and counting them would report a problem
- * where none exists.
- */
-export const MISS_FLOOR_TOKENS = 1000;
-function asUsage(value) {
-    if (!value || typeof value !== "object")
-        return undefined;
-    const candidate = value;
-    if (typeof candidate.input !== "number" && typeof candidate.cacheRead !== "number" && typeof candidate.cacheWrite !== "number")
-        return undefined;
-    return candidate;
-}
-function tokens(usage) {
-    const input = usage?.input ?? 0;
-    const cacheRead = usage?.cacheRead ?? 0;
-    // A cache WRITE is also a prompt token the provider processed; excluding it would
-    // make the rate look better than the bill.
-    const cacheWrite = usage?.cacheWrite ?? 0;
-    return { input, cacheRead, cacheWrite, prompt: input + cacheRead + cacheWrite };
-}
-function parseTime(value) {
-    if (typeof value !== "string")
-        return null;
-    const t = Date.parse(value);
-    return Number.isNaN(t) ? null : t;
-}
-/**
- * Read the usage off one session entry, or nothing.
- *
- * Entries arrive as a union the caller's session defines, so this narrows at runtime
- * rather than asserting a shape: an entry type this code has never seen contributes
- * nothing and the reading stays honest instead of turning into a crash or a nonsense
- * number.
- */
-function usageOf(entry) {
-    if (!entry || typeof entry !== "object")
-        return undefined;
-    const e = entry;
-    // Usage lives either on an assistant message or on a standalone usage entry (cache
-    // warming writes one). Both count; neither is inferred.
-    const onMessage = e.message && typeof e.message === "object" ? e.message : undefined;
-    const holder = onMessage ?? e;
-    const usage = asUsage(holder.usage);
-    if (!usage)
-        return undefined;
-    const provider = typeof holder.provider === "string" ? holder.provider : "";
-    const model = typeof holder.model === "string" ? holder.model : "";
-    return { usage, model: [provider, model].filter(Boolean).join("/") };
-}
-/**
- * Walk a session's entries and total up what was cached and what was re-billed.
- *
- * Order is the file order, which is the order the turns were sent.
- */
-export function summarizeCacheUsage(entries) {
-    let cachedTokens = 0;
-    let billedTokens = 0;
-    const misses = [];
-    let missedTokens = 0;
-    let previous = null;
-    for (const entry of entries) {
-        const found = usageOf(entry);
-        if (!found)
-            continue;
-        const { input, cacheRead, cacheWrite, prompt } = tokens(found.usage);
-        if (prompt === 0)
-            continue;
-        cachedTokens += cacheRead;
-        billedTokens += input + cacheWrite;
-        const at = parseTime(entry.timestamp);
-        // Read the previous turn before overwriting it. It is captured into a local
-        // first because TypeScript narrows `previous` to `null` once the assignment at
-        // the bottom of the loop is in scope, and the miss check below needs the old value.
-        const prior = previous;
-        const priorAt = prior ? prior.at : null;
-        // A miss is a turn that had to send its prompt with NOTHING read from cache while
-        // a previous prompt existed to be cached. One isolated occurrence is noise; the
-        // report lists them so the pattern is visible rather than the count alone.
-        if (prior !== null && cacheRead === 0 && input >= MISS_FLOOR_TOKENS) {
-            const idleMs = at !== null && priorAt !== null ? Math.max(0, at - priorAt) : 0;
-            misses.push({
-                missedTokens: input,
-                idleMs,
-                modelChanged: found.model !== "" && prior.model !== "" && found.model !== prior.model,
-            });
-            missedTokens += input;
-        }
-        previous = { prompt, at: at ?? priorAt ?? null, model: found.model };
-    }
-    const total = cachedTokens + billedTokens;
-    return {
-        cachedTokens,
-        billedTokens,
-        hitRate: total > 0 ? (cachedTokens / total) * 100 : null,
-        misses,
-        missedTokens,
-    };
-}
-/**
- * The most likely cause of a miss, for the one-line explanation beside the number.
- *
- * Reported only when there is a cause worth naming. Claiming one from thin evidence is
- * worse than saying nothing: the user cannot check a guess that has no basis in the data.
- */
-export function explainMiss(miss) {
-    if (miss.modelChanged)
-        return "model changed, so its cache had to be built";
-    if (miss.idleMs >= CACHE_TTL_MS)
-        return `cache expired after ${Math.round(miss.idleMs / 1000)}s idle`;
-    if (miss.idleMs > 0)
-        return "prompt changed too early in the prefix to hit";
-    return "reason not recorded";
-}