howtofixcli 0.7.14 → 0.7.16

package/dist/agent-defs.js

@@ -1,237 +0,0 @@
-import { readFileSync, readdirSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { getAgentDir, parseFrontmatter } from "@netrodev/hxf-coding-agent";
-import { BUILTIN_AGENT_NAMES } from "./agents.js";
-/**
- * Subagent definitions written by the user, as markdown.
- *
- * One file is one agent. The frontmatter carries what the model needs to choose
- * it and what the run needs to be set up, and the body becomes the child's
- * standing system prompt:
- *
- *     ---
- *     name: migration
- *     description: moves one module at a time and tests after each
- *     tools: read, bash, edit, write
- *     model: gemini-3-flash
- *     effort: medium
- *     ---
- *     Migrate exactly one module per turn. Run its tests before moving on, and
- *     report the file you changed and the test result.
- *
- * The parser is the harness's own, so a file means the same thing here and in
- * the harness. The locations follow this CLI's rule: everything a user writes
- * for a project lives under one directory, `.howtofix`, the same one that holds
- * project skills and presets.
- *
- *     <project>/.howtofix/agents/*.md  nearest ancestor, found by walking up
- *     ~/.howtofix/agent/agents/*.md    the CLI's own user scope
- *
- * `parseFrontmatter` is the SDK's YAML parser, which means quoted values,
- * arrays, comments and anything else YAML allows are read the same way the
- * harness reads them. The user-scope directory is the one the run store also
- * uses (`AGENTS_STORE_DIR`); the two do not collide because the store reads only
- * `*.json` and this reads only `*.md`.
- *
- * A definition replaces a built-in of the same name. That is the point of having
- * them: `scout`, `architect`, `task` and `reviewer` are a starting set, not a
- * fixed menu, and an agent whose prompt is wrong for a project should be fixable
- * without patching this package.
- */
-/** The effort levels a definition may declare. Ours, not the harness's. */
-const EFFORTS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
-/** Frontmatter keys this loader reads; anything else is reported and ignored. */
-const KEYS = ["name", "description", "tools", "model", "effort"];
-/**
- * Tools a definition may name.
- *
- * Not a permission list — the permission extension still decides what a child
- * may actually do — but a spelling list, so a typo is reported at load instead of
- * silently resolving to nothing at call time. `mcp__<server>__<tool>` names are
- * accepted as written because they cannot be known in advance.
- */
-export const KNOWN_AGENT_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls", "bash_output", "kill_shell", "todo", "context", "goal", "task", "workflow", "web_search", "web_fetch", "lsp", "quality", "claim", "repo_map"];
-/**
- * What a definition gets when it names no tools: the same set the built-in `task`
- * agent has.
- *
- * The harness leaves an absent `tools` meaning "no restriction". Here the field
- * is the child's allowlist, so absent has to mean something concrete, and a
- * working set is the useful reading: the permission extension already refuses
- * anything above the parent's approval mode inside a child, and a spawned agent
- * has no interactive UI, so the gate fails closed. Narrowing is what `tools` is
- * for.
- */
-export const DEFAULT_AGENT_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls", "context", "todo", "web_search", "web_fetch", "lsp", "claim"];
-/** `a, b` and `[a, b]` both mean two tools; anything else means none declared. */
-function asToolList(value) {
-    const raw = typeof value === "string" ? value.split(",") : Array.isArray(value) ? value : [];
-    const tools = raw
-        .map((item) => String(item)
-        .trim()
-        .replace(/^["']|["']$/g, ""))
-        .filter(Boolean);
-    return tools.length > 0 ? tools : undefined;
-}
-function isDirectory(path) {
-    try {
-        return statSync(path).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * The nearest project agent directory, walking up from `cwd`.
- *
- * Walking up is the harness's rule and the useful one: a definition written for a
- * monorepo root applies to every package under it.
- */
-export function findProjectAgentDir(cwd) {
-    let current = cwd;
-    for (;;) {
-        // Beside project skills and presets: one project directory, .howtofix, so a
-        // repository does not end up with two dot-directories holding the same kind
-        // of file.
-        const candidate = join(current, ".howtofix", "agents");
-        if (isDirectory(candidate))
-            return candidate;
-        const parent = dirname(current);
-        if (parent === current)
-            return undefined;
-        current = parent;
-    }
-}
-/**
- * The directories definitions are read from, in load order.
- *
- * User first, project last, and a later definition replaces an earlier one — so a
- * project agent wins a name collision, the precedence the harness's own subagent
- * discovery uses.
- */
-export function subagentDirs(cwd) {
-    // One user location, the one this CLI owns. The harness default, ~/.hxf/agent,
-    // is not read: two folders holding the same kind of file is how a definition
-    // ends up in the place nothing looks at.
-    const dirs = [{ scope: "user", dir: join(getAgentDir(), "agents") }];
-    const project = findProjectAgentDir(cwd);
-    if (project)
-        dirs.push({ scope: "project", dir: project });
-    return dirs;
-}
-/**
- * Parse one definition file. Pure apart from the SDK's YAML parser, so the rules
- * can be tested without touching a filesystem.
- */
-export function parseAgentDef(text, file) {
-    const notes = [];
-    const problems = [];
-    const source = text.replace(/^\uFEFF/, "");
-    if (!/^---\r?\n/.test(source)) {
-        return { notes, problems: [`${file}: no frontmatter — the file must start with --- and end the block with ---`] };
-    }
-    let frontmatter = {};
-    let body = "";
-    try {
-        const parsed = parseFrontmatter(source);
-        frontmatter = parsed.frontmatter ?? {};
-        body = (parsed.body ?? "").trim();
-    }
-    catch (error) {
-        return { notes, problems: [`${file}: the frontmatter is not readable YAML — ${error instanceof Error ? error.message : String(error)}`] };
-    }
-    for (const key of Object.keys(frontmatter)) {
-        if (!KEYS.includes(key))
-            notes.push(`${file}: ignoring the unknown frontmatter key '${key}'`);
-    }
-    // A file's own name is the natural default, so `reviewer.md` needs no `name:`.
-    const stem = (file.split(/[\\/]/).pop() ?? file).replace(/\.md$/i, "");
-    const rawName = frontmatter.name;
-    const name = (typeof rawName === "string" && rawName.trim() ? rawName : stem).trim();
-    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
-        problems.push(`${file}: '${name}' is not a usable agent name — letters, digits, dot, dash and underscore only`);
-    }
-    const rawDescription = frontmatter.description;
-    const description = typeof rawDescription === "string" ? rawDescription.trim() : "";
-    if (!description)
-        problems.push(`${file}: a description is required — it is how the model decides to use this agent`);
-    if (!body)
-        problems.push(`${file}: no prompt body — the text below the frontmatter is the agent's standing instruction`);
-    const rawEffort = frontmatter.effort;
-    const effort = typeof rawEffort === "string" ? rawEffort.trim().toLowerCase() : "";
-    if (effort && !EFFORTS.includes(effort)) {
-        problems.push(`${file}: effort '${effort}' is not one of ${EFFORTS.join(", ")}`);
-    }
-    const declared = asToolList(frontmatter.tools);
-    const tools = declared ?? [...DEFAULT_AGENT_TOOLS];
-    if (declared) {
-        const unknown = declared.filter((tool) => !KNOWN_AGENT_TOOLS.includes(tool) && !tool.startsWith("mcp__"));
-        if (unknown.length > 0) {
-            notes.push(`${file}: unknown tool${unknown.length === 1 ? "" : "s"} ${unknown.join(", ")} — kept, but nothing registers them yet`);
-        }
-    }
-    const rawModel = frontmatter.model;
-    const model = typeof rawModel === "string" && rawModel.trim() ? rawModel.trim() : undefined;
-    if (problems.length > 0)
-        return { notes, problems };
-    return {
-        def: { name, description, tools, prompt: body, effort: (effort || "medium"), model, source: file },
-        notes,
-        problems,
-    };
-}
-/**
- * Load every definition into `into`.
- *
- * Re-running cannot shuffle which definition a session runs with: the same files
- * produce the same map, and a definition only ever replaces one that loaded
- * before it.
- */
-export function loadAgentDefs(cwd, into) {
-    const loaded = [];
-    const notes = [];
-    const problems = [];
-    const scopes = [];
-    for (const { scope, dir } of subagentDirs(cwd)) {
-        let entries;
-        try {
-            entries = readdirSync(dir);
-        }
-        catch {
-            // No directory is the normal case, not a problem to report.
-            continue;
-        }
-        for (const entry of entries.filter((name) => name.toLowerCase().endsWith(".md")).sort()) {
-            const file = join(dir, entry);
-            let text;
-            try {
-                text = readFileSync(file, "utf8");
-            }
-            catch (error) {
-                problems.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
-                continue;
-            }
-            const parsed = parseAgentDef(text, file);
-            notes.push(...parsed.notes);
-            problems.push(...parsed.problems);
-            const def = parsed.def;
-            if (!def)
-                continue;
-            if (into.has(def.name)) {
-                notes.push(`${file}: replaces ${BUILTIN_AGENT_NAMES.has(def.name) ? "the built-in" : "an earlier"} '${def.name}'`);
-            }
-            into.set(def.name, def);
-            loaded.push(def);
-            if (!scopes.includes(scope))
-                scopes.push(scope);
-        }
-    }
-    if (loaded.length > 0) {
-        // The effective set, not every file read: a definition that a later one
-        // replaced is not what a session will run with, and naming it twice would
-        // read as two agents.
-        const effective = loaded.filter((def) => into.get(def.name) === def);
-        notes.unshift(`loaded ${effective.length} subagent definition${effective.length === 1 ? "" : "s"} (${scopes.join(" and ")}): ${effective.map((def) => def.name).join(", ")}`);
-    }
-    return { loaded, notes, problems };
-}

package/dist/agent-limiter.js

@@ -1,68 +0,0 @@
-/**
- * One budget for agent sessions, shared by every path that opens one.
- *
- * Two paths spawn children: the `task` tool (`drain`, up to `MAX_PARALLEL` at a
- * time) and the `workflow` tool (its own semaphore, `defaultConcurrency()`). Each
- * had its own limiter and neither knew about the other, so on a six-core box a
- * workflow could run four agents while a task call ran three — seven sessions,
- * seven provider streams, on a machine sized for far fewer. Nothing failed; the
- * box simply went quiet, which is the worst way for a limit to be missing.
- *
- * The width is the machine's, not a constant: `os.availableParallelism()`
- * respects the cgroup, so a container sized to two cores does not fan out as if
- * it owned the host. The `agents` setting overrides it for a user who knows their
- * box, and `agents=1` serialises every child — the escape hatch for a host that
- * cannot take any concurrency at all.
- */
-import { availableParallelism } from "node:os";
-import { AGENT_DIR } from "./paths.js";
-import { readWorkbenchSettings } from "./settings.js";
-/** The ceiling, whatever the machine reports. */
-export const MAX_AGENT_CONCURRENCY = 4;
-/**
- * How many agent sessions may be in flight at once, across `task` and `workflow`.
- *
- * The default leaves the host usable: two cores free for the CLI, the model's
- * own request handling, and whatever else the user is running.
- */
-export function agentConcurrency() {
-    const configured = readWorkbenchSettings(AGENT_DIR).agents;
-    if (configured !== undefined)
-        return configured;
-    return Math.max(1, Math.min(MAX_AGENT_CONCURRENCY, availableParallelism() - 2));
-}
-let active = 0;
-const waiting = [];
-/**
- * Take one slot, returning the function that releases it.
- *
- * FIFO, so a `workflow` that asks for four and a `task` that asks for three are
- * served in the order they arrived rather than by whichever retries first — an
- * unfair queue starves one path under load, which reads as a hang in that path.
- *
- * The width is read when the slot is taken, not when the module loads, so
- * changing the setting affects the next child rather than the next process.
- */
-export async function acquireAgentSlot() {
-    while (active >= agentConcurrency()) {
-        await new Promise((resolve) => waiting.push(resolve));
-    }
-    active += 1;
-    let released = false;
-    return () => {
-        if (released)
-            return;
-        released = true;
-        active -= 1;
-        waiting.shift()?.();
-    };
-}
-/** Sessions in flight right now, for a check and for `/agents`. */
-export function activeAgentCount() {
-    return active;
-}
-/** Test seam: drop the in-flight count and release everyone waiting. */
-export function resetAgentLimiterForTest() {
-    active = 0;
-    waiting.splice(0).forEach((resolve) => resolve());
-}