howtofixcli 0.7.24 → 0.7.26

package/dist/rtk.js

@@ -0,0 +1,193 @@
+/**
+ * Output compression for tool results (the "read the tool, keep the token" layer).
+ *
+ * A coding agent spends most of its context on tool output, and most of that output is
+ * not information: a `git diff` where one line in forty changed, a `grep` that matched
+ * the same import in fifty files, an `ls -R` of a `node_modules` nobody asked about.
+ * Paying full price for it shortens the effective context and, on a metered gateway,
+ * costs money for text the model will never reason about.
+ *
+ * This runs as a `tool_result` handler, which is the right seam: the result has already
+ * been produced and stored, so compression changes only what the model is asked to read,
+ * never what the tool actually returned. That distinction matters — a `bash` command that
+ * wrote a file must never be re-run or altered because its *report* was shortened.
+ *
+ * Two rules keep it honest:
+ *
+ *  - **Never invent content.** Every line the model sees came from the tool. A summary
+ *    says how many lines were dropped and where they went; it never paraphrases them.
+ *  - **Never hide a failure.** An error result, or a result the tool marked truncated,
+ *    is passed through untouched. Losing the one line that explains why a command failed
+ *    costs far more than the tokens it saves.
+ *
+ * Off by default. Compression is a trade the caller makes with knowledge of their task:
+ * a search whose whole point is a count needs every line, and a run that is skimming a
+ * large diff does not want any.
+ */
+/** Tools whose output is worth compressing. Reads and writes are already exact. */
+const COMPRESSIBLE = new Set(["bash", "grep", "find", "ls", "bash_output", "powershell"]);
+/**
+ * Tools whose lines are *progress* rather than *findings*, and so may be run-collapsed.
+ *
+ * The distinction is what the numbers mean. In `Compiling module 10 done in 30ms` the
+ * numbers are a counter and the lines are interchangeable — keeping two loses nothing.
+ * In `src/auth.ts:42: const x = 1` the numbers identify *which* finding this is, and
+ * collapsing a hundred of them into a notice deletes the answer to the search the user
+ * just ran. A grep must therefore keep every line it matched; only its redundant blanks
+ * and an elision of the middle may go.
+ */
+const RUN_COLLAPSIBLE = new Set(["bash", "bash_output", "powershell"]);
+/** Below this many lines there is nothing worth summarising. */
+export const MIN_LINES = 40;
+/** How many lines of a long run to keep at each end. */
+export const KEEP_HEAD = 12;
+export const KEEP_TAIL = 8;
+/** A run must be at least this long before it is worth collapsing. */
+export const MIN_RUN = 6;
+/**
+ * True when a line carries no information beyond its neighbours' shape.
+ *
+ * Deliberately narrow. A "useful" test that guessed would eventually drop the one line
+ * that mattered, so only plainly redundant lines qualify: repeats of the line above,
+ * separators, and blank runs.
+ */
+function isRedundant(line, previous) {
+    const trimmed = line.trim();
+    if (trimmed === "")
+        return true;
+    // A rule of only punctuation or dashes is a separator, not content.
+    if (/^[-=*_~+#]{3,}$/.test(trimmed))
+        return true;
+    if (previous !== undefined && line === previous)
+        return true;
+    return false;
+}
+/**
+ * The shape of a line, with every number run replaced by a placeholder.
+ *
+ * Numbers move; the text around them is what makes two lines the same kind of line. A
+ * trailing-only match misses the common case — `Compiling module 10 done in 30ms` has
+ * its counter in the middle, so every line looked unique and none were collapsed.
+ *
+ * Collapsing is defensible for tool output in a way it is not for, say, a claim: the
+ * output is *reproducible*. The tool can be run again, and the notice below always says
+ * how many lines went and what shape they had, so nothing is lost that cannot be
+ * recovered by re-running the command.
+ */
+function shapeOf(line) {
+    return line.replace(/\d+/g, "#").trimEnd();
+}
+function collapseNumericRuns(lines) {
+    const out = [];
+    let collapsed = 0;
+    let i = 0;
+    while (i < lines.length) {
+        const key = shapeOf(lines[i]);
+        // A line with no digits has no counter to move, so a run of them is content that
+        // happens to repeat — not progress. Only a changing number makes a run collapsible.
+        if (key === "" || !/\d/.test(lines[i])) {
+            out.push(lines[i]);
+            i += 1;
+            continue;
+        }
+        let j = i + 1;
+        while (j < lines.length && shapeOf(lines[j]) === key && /\d/.test(lines[j]))
+            j += 1;
+        const run = j - i;
+        if (run >= MIN_RUN) {
+            out.push(lines[i]);
+            out.push(`  … ${run - 2} more line${run - 2 === 1 ? "" : "s"} of the same shape …`);
+            out.push(lines[j - 1]);
+            collapsed += 1;
+        }
+        else {
+            for (let k = i; k < j; k += 1)
+                out.push(lines[k]);
+        }
+        i = j;
+    }
+    return { out, collapsed };
+}
+/**
+ * Compress one tool result, or return undefined to leave it exactly as it was.
+ *
+ * Returning `undefined` rather than the original content is the difference between
+ * "nothing to do" and "replace it with itself": the handler contract treats an omitted
+ * field as untouched, and re-sending identical content burns the work for no gain.
+ */
+export function compressToolResult(text, details, options = {}) {
+    // A result the tool already truncated has been shaped by a rule that understands the
+    // tool; second-guessing it here only risks dropping the tail it deliberately kept.
+    if (details?.truncated)
+        return undefined;
+    const lines = text.split("\n");
+    if (lines.length < MIN_LINES)
+        return undefined;
+    // 1. Drop plainly redundant lines, keeping count so the notice can be truthful.
+    const kept = [];
+    let droppedRedundant = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (isRedundant(lines[i], kept[kept.length - 1])) {
+            // Keep one blank line as a paragraph break; collapse only the runs.
+            if (lines[i].trim() === "" && kept[kept.length - 1]?.trim() !== "") {
+                kept.push("");
+                continue;
+            }
+            droppedRedundant += 1;
+            continue;
+        }
+        kept.push(lines[i]);
+    }
+    // 2. Collapse repeated-shape runs — but only for tools whose numbers are progress
+    //    rather than content. A grep's line numbers identify findings; collapsing them
+    //    would delete the answer. See RUN_COLLAPSIBLE.
+    const mayCollapseRuns = options.toolName === undefined || RUN_COLLAPSIBLE.has(options.toolName);
+    const { out: collapsedLines, collapsed } = mayCollapseRuns ? collapseNumericRuns(kept) : { out: kept, collapsed: 0 };
+    // 3. Keep both ends if it is still too long. The head carries the command and its
+    //    first results; the tail carries the failure or the summary, which is usually
+    //    why anyone reads a long output at all.
+    const head = options.head ?? KEEP_HEAD;
+    const tail = options.tail ?? KEEP_TAIL;
+    let final = collapsedLines;
+    let elided = 0;
+    if (collapsedLines.length > head + tail + MIN_RUN) {
+        elided = collapsedLines.length - head - tail;
+        final = [...collapsedLines.slice(0, head), `  … ${elided} line${elided === 1 ? "" : "s"} omitted (${head} kept from the top, ${tail} from the end) …`, ...collapsedLines.slice(collapsedLines.length - tail)];
+    }
+    const saved = droppedRedundant + collapsed;
+    if (saved === 0 && elided === 0)
+        return undefined;
+    return {
+        text: final.join("\n"),
+        stats: { before: lines.length, after: final.length, collapsed },
+    };
+}
+/**
+ * Build the extension that applies compression to tool results.
+ *
+ * `enabled` is read per call rather than captured, so toggling it mid-session takes
+ * effect on the next tool result instead of the next process.
+ */
+export function createRtkExtension(options) {
+    return (hxf) => {
+        hxf.on("tool_result", (event) => {
+            if (!options.enabled())
+                return undefined;
+            // A failure is never compressed. The line that explains it is exactly the
+            // line a heuristic is most likely to decide is redundant.
+            if (event.isError)
+                return undefined;
+            if (!COMPRESSIBLE.has(event.toolName))
+                return undefined;
+            const textPart = event.content.find((c) => c.type === "text");
+            if (!textPart || textPart.type !== "text")
+                return undefined;
+            const details = event.details;
+            const result = compressToolResult(textPart.text, details, { toolName: event.toolName });
+            if (!result)
+                return undefined;
+            const content = event.content.map((c) => (c === textPart ? { type: "text", text: result.text } : c));
+            return { content };
+        });
+    };
+}

package/dist/sandbox.js

@@ -0,0 +1,105 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { join } from "node:path";
+function isExecutable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Which sandbox this machine can actually provide, if any. */
+export function detectSandbox(platform = process.platform, pathEnv = process.env.PATH ?? "") {
+    const dirs = pathEnv.split(":").filter(Boolean);
+    const find = (name) => dirs.map((dir) => join(dir, name)).find(isExecutable);
+    if (platform === "linux") {
+        const bwrap = find("bwrap");
+        // Installed is not the same as usable: a container or a kernel with
+        // unprivileged user namespaces disabled has the binary and still refuses to
+        // create a namespace. Probing costs a few milliseconds and turns a confusing
+        // runtime failure into an honest "not available here".
+        if (!bwrap)
+            return undefined;
+        const probe = spawnSync(bwrap, ["--ro-bind", "/", "/", "--", "true"], { stdio: "ignore", timeout: 3000 });
+        return probe.status === 0 ? "bubblewrap" : undefined;
+    }
+    if (platform === "darwin")
+        return find("sandbox-exec") ? "seatbelt" : undefined;
+    return undefined;
+}
+/**
+ * The argv that re-runs `argv` inside the sandbox.
+ *
+ * The bind list is the security boundary: `/` is mounted read-only, then the
+ * project and the CLI's state directory are mounted writable over it. `/tmp` is
+ * a fresh tmpfs, so a build cannot leave anything behind outside the project.
+ * Network stays on — a coding agent that cannot reach a registry is not usable —
+ * and `--unshare-pid` is left off because some toolchains need to see the
+ * process tree.
+ */
+export function sandboxArgv(kind, paths) {
+    if (kind === "bubblewrap") {
+        return [
+            "bwrap",
+            "--die-with-parent",
+            "--new-session",
+            "--ro-bind",
+            "/",
+            "/",
+            "--dev",
+            "/dev",
+            "--proc",
+            "/proc",
+            "--tmpfs",
+            "/tmp",
+            "--bind",
+            paths.cwd,
+            paths.cwd,
+            "--bind",
+            paths.agentDir,
+            paths.agentDir,
+            "--chdir",
+            paths.cwd,
+            "--",
+            ...paths.argv,
+        ];
+    }
+    const profile = [
+        "(version 1)",
+        "(deny default)",
+        "(allow process*)",
+        "(allow signal)",
+        "(allow sysctl-read)",
+        "(allow mach-lookup)",
+        "(allow network*)",
+        "(allow file-read*)",
+        `(allow file-write* (subpath "${paths.cwd}") (subpath "${paths.agentDir}") (subpath "/tmp") (subpath "/private/tmp") (subpath "/private/var/folders"))`,
+        "",
+    ].join("\n");
+    return ["sandbox-exec", "-p", profile, ...paths.argv];
+}
+/** A sentence for the banner, so the mode is never a secret. */
+export function describeSandbox(kind) {
+    return kind === "bubblewrap"
+        ? "sandbox: bubblewrap — project writable, rest of the filesystem read-only"
+        : "sandbox: seatbelt — project writable, rest of the filesystem read-only";
+}
+/**
+ * Re-execute this process inside the sandbox and return its exit code.
+ *
+ * Called once, before any session exists, and guarded by HOWTOFIX_SANDBOXED so
+ * the re-executed process does not try to wrap itself again.
+ */
+export function enterSandbox(kind, paths) {
+    const result = spawnSync(sandboxArgv(kind, paths)[0], sandboxArgv(kind, paths).slice(1), {
+        stdio: "inherit",
+        env: { ...process.env, HOWTOFIX_SANDBOXED: "1" },
+    });
+    if (result.error) {
+        console.error(`sandbox: could not start ${kind}: ${result.error.message}`);
+        return 1;
+    }
+    return result.status ?? 1;
+}

package/dist/schema.js

@@ -0,0 +1,214 @@
+/**
+ * A small JSON Schema validator, sufficient for the `schema` option of
+ * `agent()` in a workflow script.
+ *
+ * Why not a library: `ajv` is not installed and the SDK does not export a
+ * validator, so a dependency would have to be vendored into a repo whose rule is
+ * not to re-vendor the SDK. The supported subset is the one the workflow spec names
+ * for structured output — `type`, `properties`, `required`, `items`, `enum`,
+ * `anyOf`/`oneOf`/`allOf`, `$defs`/`definitions`, `additionalProperties` — which
+ * is small enough to implement honestly, and the failure messages matter more
+ * than breadth here: they are fed back to the model as a repair turn.
+ *
+ * Validation is intentionally permissive about keywords it does not understand
+ * (they are ignored rather than failing the value), because the contract is that
+ * a reply validating against the authored schema is accepted.
+ */
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function typeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (Number.isInteger(value))
+        return "integer";
+    return typeof value;
+}
+function matchesType(value, want) {
+    const actual = typeOf(value);
+    if (want === "number")
+        return actual === "number" || actual === "integer";
+    if (want === "integer")
+        return actual === "integer";
+    return actual === want;
+}
+/** Resolve a `$ref` against the document root (`#/$defs/name` or `#/definitions/name`). */
+function resolveRef(root, ref) {
+    if (typeof ref !== "string" || !ref.startsWith("#/"))
+        return undefined;
+    let node = root;
+    for (const rawPart of ref.slice(2).split("/")) {
+        const part = rawPart.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (!isObject(node) && !Array.isArray(node))
+            return undefined;
+        node = node[part];
+    }
+    return isObject(node) ? node : undefined;
+}
+function validateNode(value, schema, root, path, issues) {
+    if (!isObject(schema))
+        return;
+    if (schema.$ref !== undefined) {
+        const target = resolveRef(root, schema.$ref);
+        if (target)
+            validateNode(value, target, root, path, issues);
+        return;
+    }
+    // Combinators. `allOf` must hold everywhere; `anyOf`/`oneOf` need a passing branch.
+    if (Array.isArray(schema.allOf)) {
+        for (const branch of schema.allOf)
+            validateNode(value, branch, root, path, issues);
+    }
+    for (const keyword of ["anyOf", "oneOf"]) {
+        const branches = schema[keyword];
+        if (!Array.isArray(branches) || branches.length === 0)
+            continue;
+        const passes = branches.filter((branch) => {
+            const scratch = [];
+            validateNode(value, branch, root, path, scratch);
+            return scratch.length === 0;
+        }).length;
+        if (keyword === "anyOf" && passes === 0)
+            issues.push({ path, message: "does not match any allowed shape" });
+        if (keyword === "oneOf" && passes !== 1)
+            issues.push({ path, message: `must match exactly one shape (matched ${passes})` });
+    }
+    const declaredType = schema.type;
+    if (declaredType !== undefined) {
+        const wanted = Array.isArray(declaredType) ? declaredType.map(String) : [String(declaredType)];
+        if (!wanted.some((want) => matchesType(value, want))) {
+            issues.push({ path, message: `expected ${wanted.join(" or ")}, got ${typeOf(value)}` });
+            return; // A wrong type makes the remaining checks noise.
+        }
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.some((option) => JSON.stringify(option) === JSON.stringify(value))) {
+        issues.push({ path, message: `must be one of ${schema.enum.map((option) => JSON.stringify(option)).join(", ")}` });
+    }
+    if (isObject(value)) {
+        const properties = isObject(schema.properties) ? schema.properties : {};
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required.map(String)) {
+                if (!(key in value))
+                    issues.push({ path: path ? `${path}.${key}` : key, message: "is required" });
+            }
+        }
+        for (const [key, propertySchema] of Object.entries(properties)) {
+            if (key in value)
+                validateNode(value[key], propertySchema, root, path ? `${path}.${key}` : key, issues);
+        }
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(value)) {
+                if (!(key in properties))
+                    issues.push({ path: path ? `${path}.${key}` : key, message: "is not an allowed property" });
+            }
+        }
+        else if (isObject(schema.additionalProperties)) {
+            for (const [key, entry] of Object.entries(value)) {
+                if (!(key in properties))
+                    validateNode(entry, schema.additionalProperties, root, path ? `${path}.${key}` : key, issues);
+            }
+        }
+    }
+    if (Array.isArray(value) && schema.items !== undefined) {
+        const items = schema.items;
+        if (Array.isArray(items)) {
+            // Tuple form: validate positionally.
+            value.forEach((entry, index) => {
+                if (index < items.length)
+                    validateNode(entry, items[index], root, `${path}[${index}]`, issues);
+            });
+        }
+        else {
+            value.forEach((entry, index) => validateNode(entry, items, root, `${path}[${index}]`, issues));
+        }
+    }
+    if (typeof value === "string") {
+        if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+            issues.push({ path, message: `is shorter than ${schema.minLength} characters` });
+        }
+        if (typeof schema.pattern === "string") {
+            try {
+                if (!new RegExp(schema.pattern).test(value))
+                    issues.push({ path, message: `does not match ${schema.pattern}` });
+            }
+            catch {
+                // An invalid pattern is the schema author's problem, not the value's.
+            }
+        }
+    }
+    if (typeof value === "number") {
+        if (typeof schema.minimum === "number" && value < schema.minimum)
+            issues.push({ path, message: `is below ${schema.minimum}` });
+        if (typeof schema.maximum === "number" && value > schema.maximum)
+            issues.push({ path, message: `is above ${schema.maximum}` });
+    }
+}
+/** Every way `value` fails `schema`. Empty means it validates. */
+export function validateSchema(value, schema) {
+    if (!isObject(schema))
+        return [];
+    const issues = [];
+    validateNode(value, schema, schema, "", issues);
+    return issues;
+}
+/** One line per issue, for a repair turn. */
+export function formatIssues(issues) {
+    return issues.map((issue) => `- ${issue.path || "(root)"}: ${issue.message}`).join("\n");
+}
+/**
+ * Pull a JSON value out of a model reply.
+ *
+ * Models wrap JSON in prose or fences often enough that a bare `JSON.parse` is
+ * not a fair test of whether they followed the schema. Only the first complete
+ * value is taken; anything before or after it is ignored.
+ */
+export function extractJson(text) {
+    const trimmed = text.trim();
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(trimmed);
+    const candidates = [trimmed, fenced?.[1]?.trim()].filter((candidate) => Boolean(candidate));
+    for (const candidate of candidates) {
+        try {
+            return JSON.parse(candidate);
+        }
+        catch {
+            /* try to find a balanced value inside */
+        }
+        for (let start = 0; start < candidate.length; start++) {
+            const opener = candidate[start];
+            if (opener !== "{" && opener !== "[")
+                continue;
+            const closer = opener === "{" ? "}" : "]";
+            let depth = 0;
+            let inString = false;
+            let escaped = false;
+            for (let index = start; index < candidate.length; index++) {
+                const char = candidate[index];
+                if (inString) {
+                    if (escaped)
+                        escaped = false;
+                    else if (char === "\\")
+                        escaped = true;
+                    else if (char === '"')
+                        inString = false;
+                    continue;
+                }
+                if (char === '"')
+                    inString = true;
+                else if (char === opener)
+                    depth++;
+                else if (char === closer) {
+                    depth--;
+                    if (depth === 0) {
+                        try {
+                            return JSON.parse(candidate.slice(start, index + 1));
+                        }
+                        catch {
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return undefined;
+}

package/dist/serve.js

@@ -0,0 +1,50 @@
+import { APP_VERSION } from "./brand.js";
+/** Adapt an opened session to the slice of it the protocol layers use. */
+export function agentFromSession(opened) {
+    return {
+        prompt: (text) => opened.session.prompt(text),
+        abort: () => opened.session.abort(),
+        subscribe: (listener) => opened.session.subscribe((event) => listener(event)),
+        getLastAssistantText: () => opened.session.getLastAssistantText(),
+        lastStopReason: () => {
+            const last = opened.session.state.messages.at(-1);
+            return last?.role === "assistant" ? last.stopReason : undefined;
+        },
+        dispose: () => opened.dispose(),
+    };
+}
+/** Run the chosen protocol on stdin/stdout until stdin closes. */
+export async function serveProtocol(mode, options) {
+    const { openSession } = await import("./session.js");
+    const open = (cwd) => openSession({
+        cwd,
+        model: options.model,
+        thinking: options.thinking,
+        continueSession: false,
+        noSession: false,
+        sessionPath: undefined,
+        // No terminal: a skill that asks a question must say so instead of waiting
+        // on a person who is not there.
+        interactive: false,
+    });
+    if (mode === "acp") {
+        const { runAcp } = await import("./acp.js");
+        await runAcp({
+            input: process.stdin,
+            output: process.stdout,
+            version: APP_VERSION,
+            createAgent: async (cwd) => agentFromSession(await open(cwd)),
+        });
+        return;
+    }
+    const { runRpc } = await import("./rpc.js");
+    const { jsonLine } = await import("./json-events.js");
+    const opened = await open(options.cwd);
+    await runRpc({
+        input: process.stdin,
+        output: process.stdout,
+        agent: agentFromSession(opened),
+        encodeEvent: (event) => jsonLine(event),
+        state: () => ({ sessionId: opened.session.sessionId, model: opened.modelLabel, cwd: options.cwd }),
+    });
+}

package/dist/session-lifecycle.js

@@ -0,0 +1,19 @@
+/**
+ * Close extension-owned resources before disposing an agent session.
+ *
+ * AgentSession.dispose() disconnects the agent itself, but extension resources
+ * (including MCP transports) are released by the session_shutdown event. The
+ * SDK exposes the runner so callers can deliver that lifecycle event even when
+ * a session is replaced outside the interactive mode.
+ *
+ * The returned promise settles once the shutdown has been delivered and the
+ * session is disposed. Callers must await it: dropping the promise leaves the
+ * MCP processes and tool registrations alive after the configuration that
+ * created them is gone.
+ */
+export function disposeAgentSession(session) {
+    return session.extensionRunner
+        .emit({ type: "session_shutdown", reason: "quit" })
+        .catch(() => undefined)
+        .finally(() => session.dispose());
+}