howtofixcli 0.7.24 → 0.7.26

package/dist/agent-defs.js

@@ -0,0 +1,237 @@
+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", "slop", "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

@@ -0,0 +1,68 @@
+/**
+ * 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());
+}