howtofixcli 0.7.24 → 0.7.26

package/dist/agents.js

@@ -0,0 +1,554 @@
+import { mkdirSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { createAgentSession, DefaultResourceLoader, SessionManager } from "@netrodev/hxf-coding-agent";
+import { AGENT_DIR, AGENTS_STORE_DIR, additionalSkillPaths } from "./paths.js";
+import { contextTool } from "./notes.js";
+import { createContextExtension } from "./context-extension.js";
+import { createPermissionExtension } from "./permissions.js";
+import { todoTool } from "./todo.js";
+import { webFetchTool, webSearchTool } from "./web-tools.js";
+import { lspTool } from "./lsp-tools.js";
+import { qualityTool } from "./quality-tool.js";
+import { claimTool } from "./tools.js";
+import { writeFileAtomicSync } from "./fs-atomic.js";
+import { acquireAgentSlot } from "./agent-limiter.js";
+import { resolveModel } from "./model-resolve.js";
+/**
+ * Coordination rule for subagents. Siblings edit the same working
+ * tree concurrently, so a project-wide build or test run started by one of them
+ * blocks on another's half-finished change and reports failures that are not
+ * real. Scoped proof of the agent's own change is what it should run.
+ */
+const SUBAGENT_COOP = [
+    "You are one agent on a shared task; siblings may be editing the same working tree right now.",
+    "Stay inside the files your assignment names. A file another agent owns is theirs to change: report what you need changed instead of changing it yourself, and never edit a file two agents were both given.",
+    "Never run project-wide validation (full builds, whole test suites, formatters, linters) unless your assignment explicitly tells you to.",
+    "Siblings' unfinished edits will make those runs fail for reasons that are not yours. Prove your own change with a scoped test, a targeted repro, or a smoke run instead.",
+];
+/**
+ * The planning agent, ported from Claude Code's built-in `Plan` agent
+ * (`src/tools/AgentTool/built-in/planAgent.ts`).
+ *
+ * The shape is the reference's, and the point is that it is read-only by
+ * construction rather than by instruction: the edit tools are not in its
+ * `tools` list, so it cannot write a file even if its prompt is ignored or
+ * overridden. The reference enforces the same thing with `disallowedTools`;
+ * naming only the read tools achieves it here.
+ *
+ * One deliberate difference: the reference gives its plan agent `Bash` and
+ * relies on the prompt to keep it to read-only commands ("NEVER use Bash for:
+ * mkdir, touch, rm, cp, mv, git add, git commit, npm install..."). This agent
+ * gets no `bash` at all, because a prompt-level promise is not a guarantee and
+ * shell redirection is exactly how a read-only agent writes a file by accident.
+ * The cost is that it cannot run `git log` to read history; it can still read
+ * every file, which is what planning needs.
+ */
+const ARCHITECT_PROMPT = `You are a software architect planning an implementation. Your job is to explore the codebase and return a plan, not to write code.
+
+## Read-only, by construction
+You have no edit tool, no write tool, and no shell. Do not attempt to modify, create, move, or delete anything — the call would fail. Your output is text.
+
+## Your process
+1. Understand the requirement. If it is ambiguous in a way that changes the design, say so and name the options rather than silently picking one.
+2. Explore: read the files involved, find the existing patterns and conventions with grep/find/ls, and trace the code paths the change touches. Follow the codebase's existing approach instead of inventing a new one.
+3. Design: state the approach you recommend, not every alternative you considered. Note the trade-off that decided it.
+4. Sequence: give the implementation as ordered steps, naming the files and functions to change at each one, and what to verify after each.
+
+## Required output
+End your reply with exactly this section, listing the 3-5 files most critical to the implementation, most important first:
+
+### Critical Files for Implementation
+- path/to/file.ts
+- path/to/file.ts
+
+Keep the plan concrete enough to execute without re-deriving it: name real paths and real function names you saw while exploring. If you could not confirm something, say which part you are unsure of instead of guessing.`;
+export const agents = new Map([
+    [
+        "scout",
+        {
+            name: "scout",
+            description: "read-only lookup",
+            tools: ["read", "grep", "find", "ls", "context", "web_search", "web_fetch", "lsp"],
+            prompt: ["Inspect only what the task needs. Do not edit.", ...SUBAGENT_COOP].join("\n"),
+            effort: "low",
+        },
+    ],
+    [
+        "architect",
+        {
+            name: "architect",
+            description: "designs an implementation plan",
+            // No edit/write, and no bash: see ARCHITECT_PROMPT. Read-only is the point.
+            // `web_search`/`web_fetch` are lookup, so they belong here too; `lsp` is a
+            // read-only language-server query, so the planner gets it as well.
+            tools: ["read", "grep", "find", "ls", "context", "web_search", "web_fetch", "lsp"],
+            prompt: ARCHITECT_PROMPT,
+            // Planning is where thinking pays for itself: the reference inherits the
+            // parent model, and the equivalent knob here is effort.
+            effort: "high",
+        },
+    ],
+    [
+        "task",
+        {
+            name: "task",
+            description: "implements the assignment",
+            tools: ["read", "bash", "edit", "write", "grep", "find", "ls", "context", "todo", "web_search", "web_fetch", "lsp"],
+            prompt: ["Do the assignment, then report files changed.", ...SUBAGENT_COOP].join("\n"),
+            effort: "medium",
+        },
+    ],
+    [
+        "reviewer",
+        {
+            name: "reviewer",
+            description: "finds concrete issues",
+            tools: ["read", "grep", "find", "ls", "context", "web_search", "web_fetch", "lsp"],
+            prompt: ["Return issues with file evidence. Do not edit.", ...SUBAGENT_COOP].join("\n"),
+            effort: "medium",
+        },
+    ],
+]);
+/**
+ * The names shipped in this package.
+ *
+ * Captured once, right after the map is built, because the map is also where
+ * definition files land. Comparing against the live map would make a file
+ * definition look like a built-in the second time the loader ran, and the
+ * "replaces the built-in" notice would then never fire.
+ */
+export const BUILTIN_AGENT_NAMES = new Set(agents.keys());
+/** `56.6k` for thousands, the raw count below that. */
+export function formatTokens(count) {
+    return count >= 1000 ? `${(count / 1000).toFixed(1)}k` : String(count);
+}
+/** `23.7s` under a minute, `1m 34.3s` above it. */
+export function formatDuration(ms) {
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    return `${Math.floor(ms / 60_000)}m ${((ms % 60_000) / 1000).toFixed(1)}s`;
+}
+/**
+ * One line saying what the child did and what it cost.
+ *
+ * The report itself is the parent's business — it is what the model reads next —
+ * but a reader watching the screen needs the shape of the work: which agent ran,
+ * how it ended, and how much it took. Without the numbers a fan-out is opaque,
+ * and the one thing that would show a runaway child is exactly what is missing.
+ *
+ * `parked` reads as `done`: the run finished and can be resumed, which is the
+ * same thing a reader means by finished.
+ */
+export function summarizeRun(run) {
+    const status = run.status === "parked" ? "done" : run.status === "error" ? "failed" : run.status;
+    const bits = [];
+    // The model is part of the shape of the work: a fan-out whose children ran on
+    // different models cannot be read from the numbers alone.
+    if (run.model)
+        bits.push(run.model);
+    if (typeof run.toolUses === "number")
+        bits.push(`${run.toolUses} tool use${run.toolUses === 1 ? "" : "s"}`);
+    if (typeof run.tokens === "number" && run.tokens > 0)
+        bits.push(formatTokens(run.tokens));
+    if (run.startedAt && run.endedAt)
+        bits.push(formatDuration(run.endedAt - run.startedAt));
+    return `## ${run.agent}#${run.id} ${status}${bits.length > 0 ? ` (${bits.join(" · ")})` : ""}`;
+}
+export const runs = [];
+/**
+ * How many children this path runs at once. The width itself lives in the shared
+ * limiter, so a `workflow` running at the same time is counted against the same
+ * budget rather than doubling it.
+ */
+const MAX_PARALLEL = 3;
+/** Follow-up prompts one run accepts before it is considered out of budget. */
+const MAX_REQUESTS = 8;
+/**
+ * How many children one call may ask for.
+ *
+ * A fan-out is the point of the tool, so the cap is above `MAX_PARALLEL` — a call
+ * for six scouts runs three, then three, and the model gets them all. What it
+ * stops is the unbounded case: nothing used to limit `tasks[]`, so one call could
+ * queue forty children, each opening a session and its own provider stream on a
+ * shared box. Measured failure mode without a cap: a fan-out the host cannot
+ * carry looks like a hang, not an error.
+ */
+export const MAX_TASKS_PER_CALL = 6;
+/**
+ * How many children may be live or parked at once, across calls.
+ *
+ * Parked runs stay resumable, so they are not free: each one holds a session
+ * record and an entry in `/agents`. Without a ceiling a long session accumulates
+ * them until every spawn adds to a list nobody prunes.
+ */
+export const MAX_AGENTS = 12;
+function persist(run) {
+    mkdirSync(AGENTS_STORE_DIR, { recursive: true });
+    writeFileAtomicSync(join(AGENTS_STORE_DIR, `${run.id}.json`), JSON.stringify({ ...run, session: undefined }, null, 1));
+}
+function loadParked() {
+    let names;
+    try {
+        names = readdirSync(AGENTS_STORE_DIR);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const saved = JSON.parse(readFileSync(join(AGENTS_STORE_DIR, name), "utf8"));
+            if (saved.status !== "parked" || runs.some((run) => run.id === saved.id))
+                continue;
+            runs.push({ ...saved, mail: saved.mail ?? [] });
+        }
+        catch {
+            // ignore unreadable run files
+        }
+    }
+    // Parked runs are resumable, which is why they are kept — and why they are
+    // not free. `spawn` already refuses past MAX_AGENTS, but it only counts what
+    // is in memory, and a fresh process starts empty and then loads every file in
+    // the store. Without a trim here the ceiling the cap exists to enforce is
+    // crossed the moment the process restarts: measured at 20 loaded against a
+    // cap of 12. The oldest go, and a session they still hold is released rather
+    // than left attached to a run nothing references any more.
+    if (runs.length > MAX_AGENTS) {
+        const dropped = runs.splice(0, runs.length - MAX_AGENTS);
+        for (const run of dropped) {
+            const session = run.session;
+            run.session = undefined;
+            if (session)
+                void session.dispose();
+            // The file is what reloads the run. Leaving it means the next process
+            // loads the same surplus and drops it again, so the store only ever grows.
+            try {
+                unlinkSync(join(AGENTS_STORE_DIR, `${run.id}.json`));
+            }
+            catch {
+                // Already gone is the state we wanted.
+            }
+        }
+    }
+}
+export function listRuns() {
+    loadParked();
+    if (runs.length === 0)
+        return "no agents";
+    const lines = runs.map((run) => `${run.id} ${run.agent} ${run.status}` + `${run.model ? ` model=${run.model}` : ""}` + `${run.background ? " background" : ""}` + ` requests=${run.requests} ${run.task}`);
+    // A background pump is the one thing a reader cannot infer from the rows: every
+    // run can read `running` while the queue behind them has not been picked up yet.
+    if (backgroundDrain)
+        lines.unshift("background work in flight");
+    return lines.join("\n");
+}
+export function showRun(id) {
+    loadParked();
+    const run = runs.find((item) => item.id === id);
+    if (!run)
+        return `no agent ${id}`;
+    return `${run.agent}#${run.id} ${run.status}\n${run.result ?? run.task}`;
+}
+/**
+ * Open the session a run executes in.
+ *
+ * Exported so the wiring can be checked against a real session rather than a
+ * mock: `scripts/check-subagent-context.mjs` uses it to read back the prompt a
+ * subagent actually receives.
+ */
+export async function openAgentSession(run) {
+    const spec = agents.get(run.agent);
+    if (!spec)
+        throw new Error(`unknown agent ${run.agent}`);
+    // The workspace is the one the run was started in, not the process's own
+    // directory. `process.cwd()` is the shell the CLI was launched from, so a
+    // subagent spawned from a session in another folder wrote its files into the
+    // CLI's directory — measured: the child reported "Files changed: DIRECT.txt"
+    // and the file appeared next to the binary instead of in the project.
+    const cwd = run.worktree || run.cwd || process.cwd();
+    // The agent's own instructions belong in the system prompt, and this loader is
+    // the only place that can put them there: `createAgentSession` has no prompt
+    // option, so a `prompt` field on the agent definition is inert unless it is
+    // handed to the loader. It was previously passed only as the leading text of
+    // the first user message, which left the child's system prompt identical to
+    // the parent's — the model read the coordination rules as part of one turn's
+    // input rather than as its standing instruction, and `check-subagent-prompt`
+    // was red because no request carried them in the system message.
+    // The shared notes only reach a subagent if the extension that injects them is
+    // loaded into the subagent's own resource loader — `customTools` alone would
+    // give it the tool but never put the notes in its prompt.
+    // The permission gate belongs on a subagent's session too. A spawned agent has
+    // no interactive UI, so `currentPrompt` keeps its deny default and every call
+    // above the mode's tier is refused instead of run — the fail-closed behaviour
+    // a sibling harness shipped as a bug when one tool skipped it. Without this the
+    // `task` tool handed its children `bash`, `edit` and `write` with nothing in
+    // front of them: `full-auto` from the parent's perspective, in a process the
+    // user never sees. Registered first so the gate decides before the context
+    // extension's hooks run.
+    const resourceLoader = new DefaultResourceLoader({
+        cwd,
+        agentDir: AGENT_DIR,
+        // The agent's own instructions, as a standing system prompt rather than the
+        // first line of a user turn. See the note above `cwd`.
+        appendSystemPrompt: [spec.prompt],
+        // A child that cannot see project skills will ignore a convention the
+        // parent just learned; the user dir is already discovered from `agentDir`.
+        // Same builder as the main session, so a subagent resolves the antislop
+        // switch exactly the way its parent did.
+        additionalSkillPaths: additionalSkillPaths(cwd),
+        extensionFactories: [createPermissionExtension({ interactive: false }), createContextExtension()],
+    });
+    await resourceLoader.reload();
+    const { session } = await createAgentSession({
+        cwd,
+        agentDir: AGENT_DIR,
+        sessionManager: SessionManager.inMemory(cwd),
+        resourceLoader,
+        tools: spec.tools,
+        // Registered for every subagent, activated only when named in `tools` above.
+        // `context` is what lets a subagent's discovery reach the parent and its
+        // siblings; `todo` is for the implementing agent, which has the longest run.
+        // The web tools and `lsp` are named in every agent's `tools` list, so they
+        // need a definition here or the name alone would resolve to nothing.
+        customTools: [contextTool, todoTool, webSearchTool, webFetchTool, lspTool, qualityTool, claimTool],
+        thinkingLevel: run.effort,
+    });
+    // A child runs on the parent's model unless the run or its definition names
+    // one. Resolved here rather than at spawn because the available list belongs
+    // to a model runtime, and there is no session to ask before this point.
+    const requested = requestedModel(run, spec);
+    if (requested) {
+        const available = await session.modelRuntime.getAvailable();
+        const resolved = resolveModel(available, requested);
+        if (!resolved) {
+            session.dispose();
+            // Where the model came from matters: an inherited model that does not
+            // resolve is a different problem from a typo in a definition.
+            const origin = run.model ? "asked for by the task" : spec.model ? `named by the ${run.agent} definition${spec.source ? ` (${spec.source})` : ""}` : "inherited from the parent session";
+            throw new Error(`unknown model '${requested}' ${origin}. /model lists what this account can reach.`);
+        }
+        await session.setModel(resolved);
+    }
+    return session;
+}
+/** Message a parked or running agent. Returns a status line. */
+export async function sendMail(id, text) {
+    loadParked();
+    const run = runs.find((item) => item.id === id);
+    if (!run)
+        return `no agent ${id}`;
+    const session = run.session ?? (await openAgentSession(run));
+    run.session = session;
+    if (run.status === "running" || session.isStreaming) {
+        run.mail.push(text);
+        persist(run);
+        return `queued for ${id}`;
+    }
+    if (run.requests >= MAX_REQUESTS)
+        return `${id} is out of budget (${run.requests} requests)`;
+    run.status = "running";
+    try {
+        await session.prompt(text);
+        run.requests += 1;
+        run.result = session.getLastAssistantText()?.trim() || run.result;
+        run.status = "parked";
+    }
+    catch (error) {
+        run.result = error instanceof Error ? error.message : String(error);
+        run.status = "error";
+    }
+    persist(run);
+    return `${id} ${run.status}`;
+}
+/**
+ * The model a child should run on: the task's own request, then its definition,
+ * then the parent session's model.
+ *
+ * The last one is the point. Without it a child runs whatever the model runtime
+ * happens to default to, which is how a `task` call came back with "model
+ * opencode/kimi-k2.6 answered nothing" while the parent was on a model the
+ * account could actually reach. An empty string counts as absent, so a blank
+ * `model:` in a definition cannot shadow the parent's.
+ */
+export function requestedModel(input, spec) {
+    // Each candidate is trimmed before it counts, so a whitespace-only value falls
+    // through to the next one instead of winning and then resolving to nothing.
+    for (const candidate of [input.model, spec.model, input.parentModel]) {
+        const trimmed = candidate?.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+/**
+ * `provider/id` for a session's current model, or undefined when it has none.
+ *
+ * Children resolve their model from a reference rather than from the parent's
+ * model object, because the two runtimes are separate instances.
+ */
+export function modelRef(model) {
+    if (!model?.provider || !model.id)
+        return undefined;
+    return `${model.provider}/${model.id}`;
+}
+export async function spawn(input) {
+    const spec = agents.get(input.agent);
+    if (!spec)
+        throw new Error(`unknown agent ${input.agent}. known: ${[...agents.keys()].join(", ")}`);
+    // Counted before the run exists, so a refused spawn does not itself grow the
+    // list it was refused for.
+    if (runs.length >= MAX_AGENTS) {
+        throw new Error(`${MAX_AGENTS} agents is the limit (${runs.length} live or parked). Finish with the existing ones, or clear them with /agents, before spawning more.`);
+    }
+    const run = {
+        id: `${Date.now().toString(36)}-${runs.length + 1}`,
+        cwd: input.cwd,
+        agent: spec.name,
+        task: input.task.trim(),
+        effort: (input.effort || spec.effort),
+        // The call wins over the definition; both are optional, and an empty string
+        // is the same as absent so a blank `model:` cannot shadow the parent's.
+        model: (input.model || spec.model)?.trim() || undefined,
+        parentModel: input.parentModel?.trim() || undefined,
+        background: input.background,
+        status: "queued",
+        requests: 0,
+        mail: [],
+        worktree: input.worktree,
+    };
+    runs.push(run);
+    persist(run);
+    return run;
+}
+async function execute(run, signal) {
+    const spec = agents.get(run.agent);
+    if (!spec)
+        return;
+    const session = run.session ?? (await openAgentSession(run));
+    run.session = session;
+    run.startedAt = Date.now();
+    try {
+        const mail = run.mail.splice(0).join("\n");
+        // The agent's instructions now live in the system prompt (see
+        // `openAgentSession`), so the turn carries only the assignment.
+        await session.prompt(`Task:\n${run.task}${mail ? `\n\nMessages:\n${mail}` : ""}`);
+        run.requests += 1;
+        while (run.mail.length > 0 && run.requests < MAX_REQUESTS) {
+            await session.followUp(run.mail.splice(0).join("\n"));
+            run.requests += 1;
+        }
+        if (signal?.aborted)
+            throw new Error("aborted");
+        // A child that produced no assistant text and called no tool did not do the
+        // work, whatever the session reports. `prompt()` can resolve without ever
+        // reaching the provider — a session that fails to issue a request still
+        // appends an empty assistant message and returns — so "it resolved" is not
+        // evidence that the run happened. Reporting that as `parked` (which
+        // `summarizeRun` prints as `done`) told the parent a child had finished when
+        // nothing had run at all. That is worse than an error: the parent acts on a
+        // result that was never produced. Marked `error` with the reason, so the
+        // report says what actually happened.
+        const lastText = session.getLastAssistantText()?.trim();
+        const stats = session.getSessionStats?.();
+        if (!lastText && (stats?.toolCalls ?? 0) === 0) {
+            throw new Error(`agent produced no output (model ${session.model?.provider}/${session.model?.id} answered nothing; 0 tool calls). ` + `Check that the provider is reachable and the model is configured.`);
+        }
+        run.result = lastText;
+        run.status = "parked";
+    }
+    catch (error) {
+        run.result = error instanceof Error ? error.message : String(error);
+        run.status = "error";
+    }
+    finally {
+        // The child's own session is the only place its work is measurable, and it
+        // is dropped before the run is persisted — so read the numbers here, while
+        // there is still something to read them from.
+        run.endedAt = Date.now();
+        const stats = session.getSessionStats?.();
+        run.toolUses = stats?.toolCalls;
+        run.tokens = stats?.tokens?.total;
+        // The session has done its work. Holding it on the run keeps the child's
+        // whole transcript, its model runtime and its extension subscriptions alive
+        // for as long as the run stays parked — and a parked run outlives the task
+        // that spawned it. A later `/agents` message reopens one through
+        // `sendMail`, which already handles a run with no session.
+        run.session = undefined;
+        session.dispose();
+        persist(run);
+        try {
+            runFinished?.(run);
+        }
+        catch {
+            // A listener is a convenience for the UI. It must never be able to take a
+            // run down with it, and a run that has already recorded its outcome has
+            // nothing left to fail.
+        }
+    }
+}
+let runFinished;
+/**
+ * Register the callback a settled run is announced through.
+ *
+ * Only background runs need this: a foreground fan-out returns its results in
+ * the tool call itself, so announcing those as well would print everything
+ * twice.
+ */
+export function setRunFinishedHandler(handler) {
+    runFinished = handler;
+}
+let backgroundDrain;
+/**
+ * Start draining without waiting for it.
+ *
+ * This is what `background: true` uses: the runs are queued, a pump is started,
+ * and the caller returns so the session can keep working. One pump at a time —
+ * a second `background` call joins the one in flight rather than starting a
+ * rival pool, because both would be pulling from the same queue anyway.
+ */
+export function startBackgroundDrain() {
+    if (backgroundDrain)
+        return;
+    backgroundDrain = drain()
+        .catch(() => {
+        // There is no caller to report to; every run recorded its own outcome.
+    })
+        .finally(() => {
+        backgroundDrain = undefined;
+    });
+}
+/**
+ * Run every queued agent, at most MAX_PARALLEL at a time.
+ */
+export async function drain(signal) {
+    // A foreground caller is asking for every queued run to finish, including the
+    // ones a `background: true` call left behind. Without this the workers below
+    // can find an empty queue — the background pump already took them — and report
+    // a fan-out as done while its children are still running.
+    if (backgroundDrain)
+        await backgroundDrain.catch(() => { });
+    const takeNext = () => runs.find((run) => run.status === "queued");
+    const worker = async () => {
+        for (;;) {
+            if (signal?.aborted)
+                throw new Error("aborted");
+            const run = takeNext();
+            if (!run)
+                return;
+            run.status = "running";
+            // The slot is held for the child's whole life, so `workflow` and `task`
+            // queue against each other instead of each honouring its own width.
+            const release = await acquireAgentSlot();
+            try {
+                await execute(run, signal);
+            }
+            finally {
+                release();
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: MAX_PARALLEL }, worker));
+    if (signal?.aborted)
+        throw new Error("aborted");
+}