howtofixcli 0.7.10 → 0.7.12

package/dist/mcp-config.js

@@ -0,0 +1,85 @@
+/**
+ * The MCP configuration the session should load, read at the moment the SDK asks.
+ *
+ * The SDK's MCP extension reads `mcp.json` exactly once, on `session_start`. A
+ * server removed from the menu afterwards stays configured as far as that
+ * extension is concerned, so nothing closes its transport and the process keeps
+ * running for the life of the CLI — the leak the preset menu could not see,
+ * because the menu only ever edited the file.
+ *
+ * The extension's teardown is correct and already exists: it closes every server
+ * whose config changed when `loadConfig` returns a set that no longer names it.
+ * What it needed was a loader that re-reads the file each time it is called, so
+ * that a change made mid-session is visible to it. That is all this is.
+ *
+ * The shape mirrors what the SDK's own loader produces, because the extension
+ * consumes it directly: `servers`, `errors`, and the project path. Entries keep
+ * whatever keys the file holds, since the SDK reads `command`, `args`, `env`,
+ * `url`, `enabled`, and `exposure` from them.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { AGENT_DIR } from "./paths.js";
+import { mcpConfigPath } from "./preset-mcp.js";
+/** The project's own `mcp.json`, which takes precedence when the project is trusted. */
+export function projectMcpConfigPath(cwd) {
+    return `${cwd}/.howtofix/mcp.json`;
+}
+/**
+ * Read one `mcp.json`. A missing file is an empty config; an unparseable one is
+ * an error, never a crash — a broken file must not stop the session from
+ * starting, and the user needs to be told which file is broken.
+ */
+function readOne(path, errors) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        const servers = parsed?.mcpServers;
+        if (!servers || typeof servers !== "object" || Array.isArray(servers))
+            return {};
+        return servers;
+    }
+    catch (error) {
+        errors.push(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return {};
+    }
+}
+/**
+ * Load global and (when trusted) project MCP configuration.
+ *
+ * Re-read on every call. The extension calls this on each `session_start`, and
+ * the session's own reload path re-emits it, so this is what turns "the file
+ * changed" into "the running session changed".
+ */
+/**
+ * The global `mcp.json` as the menu needs it: names and specs, no merging.
+ *
+ * The menu shows what a removal will act on, so it must read the same file the
+ * loader reads. A second reader here would be a second opinion about a config
+ * file, and the two would disagree the first time either changed.
+ */
+export function readGlobalMcpServers(agentDir) {
+    const errors = [];
+    return readOne(mcpConfigPath(agentDir ?? AGENT_DIR), errors);
+}
+export function loadMcpConfiguration(options) {
+    const errors = [];
+    const globalServers = readOne(mcpConfigPath(options.agentDir ?? AGENT_DIR), errors);
+    const projectPath = projectMcpConfigPath(options.cwd);
+    const projectConfig = options.projectTrusted && existsSync(projectPath) ? projectPath : undefined;
+    const projectServers = projectConfig ? readOne(projectConfig, errors) : {};
+    // The project overrides the global entry of the same name, which is the same
+    // precedence the SDK applies and the reason `/mcp` saves project overrides to
+    // this file.
+    const globalPath = mcpConfigPath(options.agentDir ?? AGENT_DIR);
+    const merged = new Map();
+    for (const [name, spec] of Object.entries(globalServers)) {
+        merged.set(name, { name, config: spec, source: globalPath, scope: "global" });
+    }
+    for (const [name, spec] of Object.entries(projectServers)) {
+        // A project entry of the same name overrides the global one, and takes over
+        // as the file `/mcp` writes to.
+        merged.set(name, { name, config: spec, source: projectConfig, scope: "project" });
+    }
+    return { servers: [...merged.values()], errors, projectConfig };
+}

package/dist/mcp-lifecycle.js

@@ -0,0 +1,147 @@
+/**
+ * One lifecycle seam for MCP configuration changes.
+ *
+ * Editing `mcp.json` and making the running session match it are two different
+ * things, and only the first was ever done. Removing a server from the preset
+ * menu wrote the file and stopped: the live transport, its child process, and the
+ * `mcp__<server>__<tool>` registrations stayed in the session until the CLI
+ * exited, so a server the user had just removed was still reachable by the agent.
+ * Installing had the mirror-image problem — the reload was a `void` call, so two
+ * quick presses could overlap a config write with a session reload and land in
+ * either order.
+ *
+ * This module owns the second half. Every path that changes MCP configuration
+ * funnels through `reconcile`, which:
+ *
+ *   - treats the on-disk configuration as the desired state and the active server
+ *     set as the actual state, then moves one toward the other;
+ *   - runs single-flight: a second request joins the one in progress rather than
+ *     starting another, and the *latest* desired state is what gets applied, so a
+ *     change made during a run is not lost;
+ *   - never lets a failure escape as an unhandled rejection, because every caller
+ *     reaches it from a `void` inside a picker handler.
+ *
+ * It deliberately does not know how the SDK starts or stops a server. The caller
+ * supplies that through `apply`, which keeps this testable without a live
+ * transport and keeps the SDK's MCP surface in one place.
+ */
+/** Raised names that could not be released. Reported, never thrown onward. */
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export class McpLifecycle {
+    /** Names currently active in the session. */
+    active;
+    apply;
+    report;
+    /** The newest desired set seen while a reconciliation was running. */
+    pending;
+    /** The in-flight reconciliation, if any. Callers join this instead of starting one. */
+    running;
+    constructor(options) {
+        this.active = new Set(options.initial ?? []);
+        this.apply = options.apply;
+        this.report = options.report ?? ((message) => console.error(message));
+    }
+    /** Names the session currently holds. A copy, so a caller cannot mutate the state. */
+    activeServers() {
+        return [...this.active];
+    }
+    /**
+     * Move the active set toward `desired`.
+     *
+     * Concurrent callers join the run in progress; the desired set is replaced
+     * before joining, so the last request wins and no edit is dropped. That is the
+     * difference between coalescing and dropping: an install that arrives while a
+     * removal is running is applied by the time the shared promise settles, not
+     * discarded because the slot was taken.
+     */
+    reconcile(desired) {
+        this.pending = new Set(desired);
+        if (this.running)
+            return this.running;
+        this.running = this.drain().finally(() => {
+            this.running = undefined;
+        });
+        return this.running;
+    }
+    /**
+     * Apply desired sets until the newest one has been applied.
+     *
+     * A single pass would leave the last request unapplied whenever a change
+     * arrived mid-run, which is exactly the case this exists for.
+     */
+    async drain() {
+        const total = { added: [], removed: [], unchanged: [], problems: [] };
+        while (this.pending !== undefined) {
+            const desired = this.pending;
+            this.pending = undefined;
+            const pass = await this.applyOnce(desired);
+            total.added.push(...pass.added);
+            total.removed.push(...pass.removed);
+            total.unchanged.push(...pass.unchanged);
+            total.problems.push(...pass.problems);
+        }
+        // Names can appear in both an add and a later remove within one reconcile
+        // call; report each name once, with the final state deciding which list.
+        const finalActive = this.active;
+        total.added = total.added.filter((name) => finalActive.has(name));
+        total.removed = [...new Set(total.removed.filter((name) => !finalActive.has(name)))];
+        total.added = [...new Set(total.added)];
+        total.unchanged = [...new Set(total.unchanged.filter((name) => finalActive.has(name)))];
+        return total;
+    }
+    async applyOnce(desired) {
+        const added = [...desired].filter((name) => !this.active.has(name));
+        const removed = [...this.active].filter((name) => !desired.has(name));
+        const unchanged = [...desired].filter((name) => this.active.has(name));
+        if (added.length === 0 && removed.length === 0) {
+            return { added: [], removed: [], unchanged, problems: [] };
+        }
+        try {
+            await this.apply(added, removed);
+        }
+        catch (error) {
+            // The session may be partly reconciled. Report which half failed rather
+            // than claiming the configuration and the session agree.
+            const message = `mcp reconciliation failed: ${describeError(error)}`;
+            this.report(message);
+            return { added: [], removed: [], unchanged: [], problems: [message] };
+        }
+        // Recorded only after `apply` resolves: a teardown that threw has not
+        // released the server, so the active set must still name it or the next
+        // reconcile would skip the release it still owes.
+        for (const name of added)
+            this.active.add(name);
+        for (const name of removed)
+            this.active.delete(name);
+        return { added, removed, unchanged, problems: [] };
+    }
+    /**
+     * Release everything this session owns.
+     *
+     * Called when the session is replaced or the CLI exits. Without it, repeated
+     * `/new` and `/resume` accumulate one set of server processes per session,
+     * which is the leak the picker path could not see because it never disposes a
+     * session at all.
+     */
+    async dispose() {
+        // A reconcile still in flight owns the transports; wait for it so we do not
+        // dispose a set it is in the middle of mutating.
+        if (this.running)
+            await this.running.catch(() => undefined);
+        const names = [...this.active];
+        if (names.length === 0)
+            return { added: [], removed: [], unchanged: [], problems: [] };
+        try {
+            await this.apply([], names);
+            this.active.clear();
+            return { added: [], removed: names, unchanged: [], problems: [] };
+        }
+        catch (error) {
+            const message = `mcp teardown failed: ${describeError(error)}`;
+            this.report(message);
+            return { added: [], removed: [], unchanged: [], problems: [message] };
+        }
+    }
+}

package/dist/model-catalog.js

@@ -0,0 +1,217 @@
+/**
+ * Real context windows and reasoning support, from models.dev.
+ *
+ * `GET /v1/models` on the gateway returns ids and nothing else — verified against
+ * the live service, whose response carries only `id`, `object`, `created`,
+ * `owned_by` and `supported_endpoint_types`. So a synced model has no declared
+ * window and no declared capability, and `/connect` filled the gap with two
+ * guesses that were both wrong in the same direction:
+ *
+ *   - `contextWindow: 128_000` for every model. The gateway serves models with
+ *     1,000,000-token windows (deepseek-v4.1-flash, kimi-k3, mimo-v2.5), so the
+ *     context meter read ~8x too full and the CLI compacted a conversation that
+ *     had barely started.
+ *   - no `reasoning` field at all. The SDK gates thinking on it — the schema is
+ *     `reasoning: boolean`, and `getSupportedThinkingLevels` returns `["off"]`
+ *     the moment it is falsy — so every synced model lost its thinking levels
+ *     even though the model reasons. That is the bug a user reports as "thinking
+ *     is missing on a model that has it".
+ *
+ * models.dev publishes exactly these facts per model (`limit.context`,
+ * `limit.output`, `reasoning`). It is a public catalogue, so the CLI can read it
+ * instead of guessing. Nothing here is bundled: the catalogue is fetched once,
+ * slimmed to the three fields that are used, and cached next to the agent state,
+ * so a later start can repair models without a network call.
+ *
+ * The pure half (index, lookup) is separated from the network half so the
+ * matching rules are testable without a fetch.
+ */
+/** Where the catalogue lives. One document, every provider. */
+export const MODELS_DEV_URL = "https://models.dev/api.json";
+/** How long to wait for the catalogue. It is ~5 MB, so this is generous. */
+export const CATALOG_TIMEOUT_MS = 20_000;
+/**
+ * Providers whose entry wins when the same model is listed by several.
+ *
+ * The catalogue is community-maintained and mirrors every reseller, so one model
+ * id resolves to a dozen near-identical entries. The first-party listing is the
+ * one whose numbers describe the model rather than a middleman's limits, so the
+ * search prefers it. Order matters only among the preferred set; everything else
+ * is ordered alphabetically so the result never depends on object iteration.
+ */
+const PREFERRED_PROVIDERS = ["anthropic", "openai", "google", "deepseek", "zai", "xai", "moonshotai", "minimax", "alibaba", "xiaomi", "meta", "tencent", "nvidia", "venice", "openrouter"];
+/** The comparison form of a model id: case and punctuation are not meaningful. */
+export function normalizeModelId(id) {
+    return id.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+/** The last path segment of an id, normalized: `z-ai/glm-5.3-fast` -> `glm53fast`. */
+function lastSegment(id) {
+    const parts = id.split("/");
+    return normalizeModelId(parts[parts.length - 1] ?? id);
+}
+/**
+ * Index every model in the catalogue document.
+ *
+ * One entry per normalized id; when several providers list the same model, the
+ * preferred provider wins (see {@link PREFERRED_PROVIDERS}). A model whose entry
+ * carries no `limit.context` is skipped: without a window there is nothing to
+ * correct, and indexing it would let a bad entry shadow a good one.
+ */
+export function buildCatalogIndex(raw) {
+    const index = new Map();
+    const owners = new Map();
+    if (!raw || typeof raw !== "object")
+        return index;
+    const providers = raw;
+    const priority = (provider) => {
+        const at = PREFERRED_PROVIDERS.indexOf(provider);
+        return at === -1 ? PREFERRED_PROVIDERS.length : at;
+    };
+    // Sorted so the winner among equally-preferred providers is decided by name,
+    // not by the insertion order of a parsed JSON object — this number feeds a
+    // token budget, so it must not depend on how the document happened to be built.
+    for (const provider of Object.keys(providers).sort()) {
+        const models = providers[provider]?.models;
+        if (!models || typeof models !== "object")
+            continue;
+        for (const id of Object.keys(models)) {
+            const model = models[id];
+            const context = Number(model?.limit?.context);
+            if (!Number.isFinite(context) || context <= 0)
+                continue;
+            const key = normalizeModelId(id);
+            const rank = priority(provider);
+            const held = owners.get(key);
+            // A preferred provider always wins; otherwise the first (alphabetical) one
+            // keeps the slot. Never let a later, less-preferred listing overwrite it.
+            if (held !== undefined && held <= rank)
+                continue;
+            const output = Number(model?.limit?.output);
+            index.set(key, {
+                contextWindow: Math.floor(context),
+                maxTokens: Number.isFinite(output) && output > 0 ? Math.floor(output) : undefined,
+                reasoning: model?.reasoning === true,
+                vision: Array.isArray(model?.modalities?.input) && model.modalities.input.includes("image"),
+            });
+            owners.set(key, rank);
+        }
+    }
+    return index;
+}
+/**
+ * The catalogue entry for a gateway model id, or undefined when it is unknown.
+ *
+ * Three passes, in order of how literal the match is: the whole id, the last path
+ * segment, then a suffix. The gateway renames models (`deepseek-v4.1-flash` is
+ * `DeepSeek-V4.1-Flash` in the catalogue, `glm-5.3-flash` is `zai/glm-5.3-flash`)
+ * and drops vendor prefixes (`anthropic/claude-sonnet-5` keeps its own), so a
+ * single exact match finds less than half. A miss is not a failure: the caller
+ * keeps its conservative default, which is the behaviour before this module.
+ */
+export function lookupModel(index, id) {
+    const wanted = normalizeModelId(id);
+    if (!wanted)
+        return undefined;
+    const exact = index.get(wanted);
+    if (exact)
+        return exact;
+    const wantedTail = lastSegment(id);
+    for (const [key, entry] of index) {
+        if (lastSegment(key) === wantedTail)
+            return entry;
+    }
+    for (const [key, entry] of index) {
+        if (key.endsWith(wanted) || wanted.endsWith(key))
+            return entry;
+    }
+    return undefined;
+}
+/** Where the slimmed catalogue is cached, so a later start needs no network. */
+export function catalogCachePath(agentDir) {
+    return `${agentDir}/models-dev-cache.json`;
+}
+/**
+ * The serialized form of an index: `{ id: [context, output, reasoning, vision] }`.
+ *
+ * An array rather than an object per entry because the catalogue is 8,000+ rows
+ * and repeating the keys eight thousand times triples the file for no reader's
+ * benefit. The cache is internal — nothing outside this module parses it.
+ *
+ * `vision` was added after the first release, so a cache written by the older
+ * build is a 3-tuple. {@link deserializeCatalog} reads the fourth slot as
+ * optional and defaults it to `false`, which is the behaviour that build had;
+ * the next fetch fills it in. Bumping a format number would instead throw the
+ * whole cache away and cost every user a 5 MB download on the next start.
+ */
+export function serializeCatalog(index) {
+    const out = {};
+    for (const [key, entry] of index) {
+        out[key] = [entry.contextWindow, entry.maxTokens ?? 0, entry.reasoning ? 1 : 0, entry.vision ? 1 : 0];
+    }
+    return JSON.stringify(out);
+}
+/** Read back {@link serializeCatalog}. Returns an empty index for anything unusable. */
+export function deserializeCatalog(text) {
+    const index = new Map();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return index;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return index;
+    for (const [key, value] of Object.entries(parsed)) {
+        if (!Array.isArray(value) || value.length < 3)
+            continue;
+        const context = Number(value[0]);
+        const output = Number(value[1]);
+        if (!Number.isFinite(context) || context <= 0)
+            continue;
+        index.set(key, {
+            contextWindow: Math.floor(context),
+            maxTokens: Number.isFinite(output) && output > 0 ? Math.floor(output) : undefined,
+            reasoning: value[2] === 1 || value[2] === true,
+            // Absent in a cache written before this field existed: read it as "no
+            // vision", which is what that build assumed, and let the next fetch correct it.
+            vision: value[3] === 1 || value[3] === true,
+        });
+    }
+    return index;
+}
+/**
+ * Fetch the catalogue and index it.
+ *
+ * Never throws: a catalogue that cannot be fetched is a reason to keep the
+ * conservative defaults, not a reason for `/connect` to fail. The caller reports
+ * which of the two happened.
+ */
+export async function fetchCatalog(options) {
+    const url = options?.url ?? MODELS_DEV_URL;
+    const doFetch = options?.fetchImpl ?? fetch;
+    const timeoutMs = options?.timeoutMs ?? CATALOG_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await doFetch(url, { signal: controller.signal, headers: { Accept: "application/json" } });
+        if (!response.ok) {
+            return { ok: false, message: `the model catalogue answered ${response.status}` };
+        }
+        const index = buildCatalogIndex(await response.json());
+        if (index.size === 0) {
+            return { ok: false, message: "the model catalogue was empty or in an unexpected shape" };
+        }
+        return { ok: true, index };
+    }
+    catch (cause) {
+        const aborted = cause instanceof Error && cause.name === "AbortError";
+        return {
+            ok: false,
+            message: aborted ? `the model catalogue did not answer within ${Math.round(timeoutMs / 1000)}s` : "could not reach the model catalogue",
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/model-facts.js

@@ -0,0 +1,35 @@
+/**
+ * The two facts a model picker is useless without: how much context it takes and
+ * what it costs.
+ *
+ * Every model entry already carries `contextWindow` and `cost`, but the picker
+ * showed only the provider, so a free model and an expensive one looked the
+ * same. These helpers turn those numbers into one short line for the list.
+ */
+/** 200000 -> "200K", 1000000 -> "1M", 1500000 -> "1.5M". Empty when unknown. */
+export function formatContextWindow(tokens) {
+    if (!tokens || !Number.isFinite(tokens) || tokens <= 0)
+        return "";
+    if (tokens >= 1_000_000) {
+        // Rounded to one decimal, then trimmed: 1_048_576 is "1M", not "1.0M".
+        return `${Number((tokens / 1_000_000).toFixed(1))}M`;
+    }
+    if (tokens >= 1_000)
+        return `${Math.round(tokens / 1_000)}K`;
+    return String(tokens);
+}
+/** Price per million tokens for input and output, or "free" when both are zero. */
+export function formatModelPrice(cost) {
+    if (!cost)
+        return "";
+    if (cost.input <= 0 && cost.output <= 0)
+        return "free";
+    const money = (value) => (value === 0 ? "0" : String(Number(value >= 1 ? value.toFixed(2) : value.toFixed(3))));
+    return `$${money(cost.input)}/$${money(cost.output)} per M`;
+}
+/** "1M ctx · free" — the summary shown beside a model in the picker. */
+export function describeModelFacts(model) {
+    const context = formatContextWindow(model.contextWindow);
+    const price = formatModelPrice(model.cost);
+    return [context ? `${context} ctx` : "", price].filter(Boolean).join(" · ");
+}

package/dist/model-resolve.js

@@ -0,0 +1,65 @@
+/**
+ * Resolve a model spec the way the CLI's own `--model` flag does.
+ *
+ * Exact `provider/id` or a bare `id` first, then a case-insensitive substring
+ * match, so both the name `/model` prints and a shorthand work. Lifted out of
+ * `session.ts` when subagents gained a model of their own: two resolvers would
+ * drift, and a subagent picking a different model than the parent asked for
+ * would read as the option being broken.
+ */
+export function resolveModel(models, spec) {
+    const exact = models.find((model) => `${model.provider}/${model.id}` === spec || model.id === spec);
+    if (exact)
+        return exact;
+    const needle = spec.toLowerCase();
+    return models.find((model) => model.id.toLowerCase().includes(needle) || `${model.provider}/${model.id}`.toLowerCase().includes(needle));
+}
+/**
+ * Order a catalogue for choosing a default model, best first.
+ *
+ * A gateway lists its catalogue in no useful order — `anthropic/claude-opus-4.8`
+ * can come first while the fast general-purpose models are far down the list — so
+ * "use whatever is first" hands a new user the most expensive thing on the
+ * account, or an image model that cannot hold a conversation.
+ *
+ * Image, embedding, audio and video models are pushed to the end: they cannot
+ * answer a coding prompt, so selecting one would look like a broken install. The
+ * caller then probes the first few and takes the first that answers.
+ */
+const PREFERRED_FAMILIES = ["deepseek", "qwen", "claude", "gpt-5", "gpt-4", "gemini", "glm", "mimo", "kimi", "llama"];
+const NOT_CHAT = /(image|embedding|embed|whisper|tts|audio|video|rerank|moderation|dall-e|stable-diffusion|sora)/i;
+export function orderModelsForDefault(ids) {
+    const rank = (id) => {
+        if (NOT_CHAT.test(id))
+            return 100;
+        const family = PREFERRED_FAMILIES.findIndex((name) => id.toLowerCase().includes(name));
+        return family === -1 ? 50 : family;
+    };
+    // Stable within a rank, so the gateway's own order decides ties.
+    return ids
+        .map((id, index) => ({ id, index }))
+        .sort((a, b) => rank(a.id) - rank(b.id) || a.index - b.index)
+        .map((entry) => entry.id);
+}
+/**
+ * The model a session should start on when nothing was asked for.
+ *
+ * The model runtime knows every model in the catalog it ships, including
+ * providers this account holds no credential for, and its own default is the
+ * catalog's — `opencode/kimi-k2.6` — not the account's. Starting there is not a
+ * cosmetic problem: the first prompt goes to a provider that cannot answer and
+ * comes back as an empty assistant message, with nothing in the transcript to
+ * explain why it looks hung.
+ *
+ * So the default comes from the models that are actually available, and a
+ * HowToFix provider wins over any other reachable one: an install that signed in
+ * to HowToFix should run HowToFix's models.
+ */
+export function defaultModelFor(available, ownProviders = []) {
+    if (available.length === 0)
+        return undefined;
+    const own = available.filter((model) => ownProviders.includes(model.provider));
+    const pool = own.length > 0 ? own : available;
+    const first = orderModelsForDefault(pool.map((model) => model.id))[0];
+    return pool.find((model) => model.id === first) ?? pool[0];
+}

package/dist/notes.js

@@ -0,0 +1,78 @@
+/**
+ * A shared scratchpad for facts that must survive context compaction and reach
+ * every agent working on the task.
+ *
+ * A shared notes store for the session.
+ * Why it matters: the `task` tool spawns subagents with their own context
+ * window, so anything the main agent learned while scouting is invisible to them,
+ * and anything they discover dies with their run. A note written once is visible
+ * to the parent and to every sibling, and it survives a compaction that would
+ * otherwise drop the discovery from the transcript.
+ *
+ * The store is process-wide on purpose: `agents.ts` opens subagent sessions in
+ * this same process, so they share it. It is in-memory only — notes are working
+ * state for one session, not project documentation (that is `AGENTS.md`).
+ */
+import { StringEnum } from "@netrodev/hxf-ai";
+import { defineTool } from "@netrodev/hxf-coding-agent";
+import { Type } from "typebox";
+const notes = new Map();
+/** Longest note accepted, so one call cannot flood every later request. */
+const MAX_VALUE = 2000;
+/** Longest key accepted; keys are the lookup handle, so they stay short. */
+const MAX_KEY = 80;
+export function clearNotes() {
+    notes.clear();
+}
+export function noteCount() {
+    return notes.size;
+}
+/** The block injected into the prompt, or an empty string when there is nothing. */
+export function renderNotes() {
+    if (notes.size === 0)
+        return "";
+    const lines = [...notes].map(([key, value]) => `- ${key}: ${value}`);
+    return ["<shared-notes>", "Working notes recorded with the `context` tool. They survive compaction and are visible to every agent on this task.", ...lines, "</shared-notes>"].join("\n");
+}
+export function applyNote(op, key, value) {
+    if (op === "list") {
+        if (notes.size === 0)
+            return { text: "No notes." };
+        return { text: [...notes].map(([k, v]) => `${k} = ${v}`).join("\n") };
+    }
+    if (!key)
+        return { text: "Error: key is required", error: "key required" };
+    if (key.length > MAX_KEY)
+        return { text: `Error: key longer than ${MAX_KEY} characters`, error: "key too long" };
+    if (op === "forget") {
+        const existed = notes.delete(key);
+        return { text: existed ? `Removed ${key}` : `No note named ${key}` };
+    }
+    if (op === "set") {
+        if (!value)
+            return { text: "Error: value is required for set", error: "value required" };
+        const clipped = value.length > MAX_VALUE ? `${value.slice(0, MAX_VALUE)}…` : value;
+        notes.set(key, clipped);
+        return { text: `Recorded ${key} (${notes.size} note${notes.size === 1 ? "" : "s"} held)` };
+    }
+    return { text: `Error: unknown op ${JSON.stringify(op)}`, error: "unknown op" };
+}
+export const contextTool = defineTool({
+    name: "context",
+    label: "context",
+    description: "Record a durable working note (a decision, a file's role, a fact you would otherwise re-derive). Notes survive context compaction and are visible to every agent on this task, including subagents. Use `set` to write, `list` to read, `forget` to remove.",
+    promptSnippet: "context: durable notes shared with every agent on this task",
+    parameters: Type.Object({
+        op: StringEnum(["set", "list", "forget"], { description: "set writes a note, list reads all, forget removes one" }),
+        key: Type.Optional(Type.String({ description: "Short lookup key, e.g. 'auth-entrypoint'" })),
+        value: Type.Optional(Type.String({ description: "The fact to keep (for set)" })),
+    }),
+    async execute(_toolCallId, params) {
+        const { text, error } = applyNote(params.op, params.key, params.value);
+        return {
+            content: [{ type: "text", text }],
+            details: { op: params.op, notes: Object.fromEntries(notes) },
+            ...(error ? { isError: true } : {}),
+        };
+    },
+});