heedvane 0.0.0-stage → 0.2.0

package/dist/clients/hermes-plugin.js

@@ -0,0 +1,247 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+const HERMES_PLUGIN_NAME = "heedvane-hooks";
+/**
+ * The hooks this plugin registers with the Hermes host. `pre_tool_call` and `pre_llm_call` are directive
+ * hooks: Hermes acts on what they return. `on_session_end` fires once per turn despite its name;
+ * `on_session_finalize` is the session's end (https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks).
+ */
+export const HERMES_EVENTS = [
+    "on_session_start",
+    "pre_llm_call",
+    "pre_tool_call",
+    "post_tool_call",
+    "pre_approval_request",
+    "post_approval_response",
+    "on_session_end",
+    "on_session_finalize",
+];
+const PLUGIN_YAML = `name: heedvane-hooks
+version: 1.0.0
+description: 'Reports coding-agent lifecycle events to the heedvane listener.'
+author: 'Heedvane'
+kind: standalone
+provides_hooks:
+${HERMES_EVENTS.map((event) => `  - ${event}\n`).join("")}`;
+const pluginInitPy = (gating) => `"""Heedvane agent-hooks plugin for Hermes.
+
+Reports coding-agent lifecycle events to the local heedvane listener
+(http://127.0.0.1:<port>/hook/hermes) with the shared token.
+
+The listener's answer goes back to the host: a tool block on pre_tool_call,
+turn context on pre_llm_call. Best-effort by contract: a slow, absent, or
+misconfigured listener must never block the host or raise into it, so any
+failure answers None and the host carries on.
+Configuration comes from the HEED_AGENT_HOOK_PORT / HEED_AGENT_HOOK_TOKEN
+env vars, falling back to the user's ~/.heed/endpoint.env (KEY=VALUE lines).
+Which sessions report follows heed.yaml gating.mode, baked in at setup: with
+"pane" only sessions launched with HEED_SESSION set, with "always" every one.
+"""
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+# The hooks registered with the host via register(ctx).
+EVENTS = (
+${HERMES_EVENTS.map((event) => `    "${event}",\n`).join("")})
+
+REQUEST_TIMEOUT_S = 0.75
+
+GATING = "${gating}"
+
+
+def _endpoint_from_env():
+    port = os.environ.get("HEED_AGENT_HOOK_PORT")
+    token = os.environ.get("HEED_AGENT_HOOK_TOKEN")
+    if port and token:
+        return (port, token)
+    return None
+
+
+def _endpoint_from_home_file():
+    """Parse ~/.heed/endpoint.env (KEY=VALUE lines, mode 0600)."""
+    path = os.path.join(os.path.expanduser("~"), ".heed", "endpoint.env")
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            lines = handle.read().splitlines()
+    except OSError:
+        return None
+    values = {}
+    for raw in lines:
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+            value = value[1:-1]
+        values[key.strip()] = value
+    port = values.get("HEED_AGENT_HOOK_PORT")
+    token = values.get("HEED_AGENT_HOOK_TOKEN")
+    if port and token:
+        return (port, token)
+    return None
+
+
+def _resolve_endpoint():
+    endpoint = _endpoint_from_env()
+    if endpoint is not None:
+        return endpoint
+    return _endpoint_from_home_file()
+
+
+def _post_to_listener(hook_event_name, cwd, payload):
+    """POST one event to the listener and return its decoded answer, or None.
+    Best-effort: never raises."""
+    if GATING != "always" and not os.environ.get("HEED_SESSION"):
+        return None
+    endpoint = _resolve_endpoint()
+    if endpoint is None:
+        return None
+    port, token = endpoint
+    # Flat like every other harness: the host's fields (tool_name, tool_input, ...) at the top level.
+    event = dict(payload)
+    event["hook_event_name"] = hook_event_name
+    event["cwd"] = cwd
+    body = json.dumps(event, default=str).encode("utf-8")
+    request = urllib.request.Request(
+        "http://127.0.0.1:" + str(port) + "/hook/hermes",
+        data=body,
+        headers={
+            "Content-Type": "application/json",
+            "X-Heed-Agent-Hook-Token": token,
+            "X-Heed-Hook-Version": "1",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=REQUEST_TIMEOUT_S) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except (OSError, urllib.error.URLError, ValueError):
+        # OSError covers socket errors/timeouts (URLError subclasses it);
+        # ValueError covers a malformed port or URL and an answer that is not
+        # JSON. Silent by design: a hook must never raise into the host.
+        return None
+
+
+def _extract(payload):
+    """Return (cwd, normalized payload) from whatever the host hands us."""
+    if not isinstance(payload, dict):
+        payload = {"data": payload}
+    cwd = payload.get("cwd") or os.getcwd()
+    return cwd, payload
+
+
+def _hook_payload(args, kwargs):
+    """The event's fields however the host passes them: a payload kwarg, keyword fields
+    (tool_name, args, session_id, ...) or one positional dict. Hermes' tool arguments
+    (args) become tool_input, the field every other harness uses."""
+    payload = kwargs.get("payload")
+    if payload is None:
+        payload = dict(kwargs) if kwargs else (args[0] if args else {})
+    if isinstance(payload, dict) and "tool_input" not in payload and isinstance(payload.get("args"), dict):
+        payload = dict(payload)
+        payload["tool_input"] = payload.pop("args")
+    return payload
+
+
+def _make_hook(event):
+    """The host callback for one event. It returns the listener's answer when that is a
+    non-empty object ({"action": "block", ...} on pre_tool_call, {"context": ...} on
+    pre_llm_call), and None, Hermes' "no directive", otherwise."""
+    def _hook(*args, **kwargs):
+        try:
+            cwd, normalized = _extract(_hook_payload(args, kwargs))
+            answer = _post_to_listener(event, cwd, normalized)
+        except Exception:  # absolute last resort: never raise into the host
+            return None
+        return answer if isinstance(answer, dict) and answer else None
+    _hook.__name__ = "heedvane_" + str(event)
+    return _hook
+
+
+def register(ctx):
+    """Register every hook in EVENTS. Called by the Hermes plugin loader."""
+    for event in EVENTS:
+        ctx.register_hook(event, _make_hook(event))
+`;
+/** The two files that make up the Hermes plugin, ready to install. */
+export function hermesPluginFiles(gating = "always") {
+    return [
+        { relativePath: "plugin.yaml", content: PLUGIN_YAML },
+        { relativePath: "__init__.py", content: pluginInitPy(gating) },
+    ];
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readFileOrNull(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+function isHeedOwned(pluginYaml) {
+    try {
+        const manifest = parseYaml(pluginYaml);
+        return typeof manifest === "object" && manifest !== null && manifest.name === HERMES_PLUGIN_NAME;
+    }
+    catch {
+        return false; // unparseable manifest — not provably ours
+    }
+}
+/** Does `<home>/.hermes/plugins/heedvane-hooks/plugin.yaml` declare our plugin? Uninstall removes only then. */
+export async function hermesPluginOwned(home) {
+    const manifest = await readFileOrNull(join(home, ".hermes", "plugins", HERMES_PLUGIN_NAME, "plugin.yaml"));
+    return manifest !== null && isHeedOwned(manifest);
+}
+/**
+ * Install the Hermes plugin into `<home>/.hermes/plugins/heedvane-hooks/`.
+ *
+ * - "skipped"  — a foreign plugin owns the target directory. Whether Hermes is installed at all
+ *                is the planner's decision (detected, or named with `--agent`).
+ * - "unchanged" — the dir is heed-owned and every file already matches.
+ * - "installed" — files were written (fresh install or update).
+ *
+ * A heed-owned directory is one whose plugin.yaml exists and contains
+ * `name: heedvane-hooks`. Differing heed-owned files are backed up to
+ * `<file>.heedvane.backup` before being replaced. Foreign plugin.yaml files
+ * are never overwritten.
+ */
+export async function installHermesPlugin(home, gating = "always") {
+    const pluginDir = join(home, ".hermes", "plugins", HERMES_PLUGIN_NAME);
+    if (await pathExists(pluginDir)) {
+        const marker = await readFileOrNull(join(pluginDir, "plugin.yaml"));
+        if (marker === null || !isHeedOwned(marker)) {
+            return "skipped"; // foreign plugin owns this directory — never overwrite
+        }
+    }
+    let changed = false;
+    await mkdir(pluginDir, { recursive: true });
+    for (const file of hermesPluginFiles(gating)) {
+        const target = join(pluginDir, file.relativePath);
+        const current = await readFileOrNull(target);
+        if (current === file.content)
+            continue;
+        if (current !== null) {
+            // Heed-owned but drifted: keep the old bytes for operator recovery.
+            await writeFile(`${target}.heedvane.backup`, current, "utf8");
+        }
+        await writeFile(target, file.content, "utf8");
+        changed = true;
+    }
+    return changed ? "installed" : "unchanged";
+}

package/dist/commands/heedvane.d.ts

@@ -0,0 +1,15 @@
+export interface BackendCommandContext {
+    home: string;
+    out: (line: string) => void;
+    /** The positional words after the command. */
+    words: string[];
+    project: boolean;
+    readStdin: () => Promise<string>;
+    openBrowser: (url: string) => void;
+}
+/** `npx heedvane login`: browser sign-in through Heedvane's OAuth server (src/backend/login.ts). */
+export declare function cmdLogin(ctx: BackendCommandContext): Promise<number>;
+/** `npx heedvane auth org`: the key arrives on stdin, so it never lands in shell history. */
+export declare function cmdAuth(ctx: BackendCommandContext): Promise<number>;
+/** `npx heedvane skills sync [--project]`: home skill dirs by default, the current project's with --project. */
+export declare function cmdSkills(ctx: BackendCommandContext): Promise<number>;

package/dist/commands/heedvane.js

@@ -0,0 +1,74 @@
+/**
+ * The commands that talk to the Heedvane backend: `auth` stores a key, `skills sync` installs the
+ * organization's approved skills and caches the list the skill check enforces.
+ */
+import { join } from "node:path";
+import { callHeedvane } from "../backend/client.js";
+import { backendAt, saveCredential } from "../backend/credentials.js";
+import { withSignInChange } from "../backend/sign-in-change.js";
+import { login } from "../backend/login.js";
+import { heedvaneConfigAt } from "../heed-file.js";
+import { syncApprovedSkills } from "../skills/approved.js";
+import { errorMessage } from "../guards.js";
+/** `npx heedvane login`: browser sign-in through Heedvane's OAuth server (src/backend/login.ts). */
+export async function cmdLogin(ctx) {
+    const root = join(ctx.home, ".heed");
+    try {
+        const { url } = heedvaneConfigAt(root);
+        const tokens = await withSignInChange(root, url, () => login(root, url, { openBrowser: ctx.openBrowser, out: ctx.out }));
+        ctx.out(`  ✓ signed in${tokens.organizationId === undefined ? "" : ` to organization ${tokens.organizationId}`} (~/.heed/login.json, mode 0600)`);
+        const probe = await callHeedvane({ url, credential: async () => ({ bearer: tokens.accessToken, identity: null }), identity: async () => null }, { method: "GET", path: "/api/agent/steering/rules", timeoutMs: 10_000 });
+        if (probe?.status === 401) {
+            ctx.out(`  ⚠ ${url} does not accept the sign-in on its agent routes yet (401): steering, skills and event forwarding stay off with it.`);
+            ctx.out("    while signed in, no organization key is used; to use one until Heedvane accepts the sign-in, delete ~/.heed/login.json and run npx heedvane auth org < key-file");
+        }
+        ctx.out("    a running listener picks it up when restarted: npx heedvane listener start");
+        return 0;
+    }
+    catch (err) {
+        ctx.out(`  ✗ sign-in failed: ${errorMessage(err)}`);
+        return 1;
+    }
+}
+/** `npx heedvane auth org`: the key arrives on stdin, so it never lands in shell history. */
+export async function cmdAuth(ctx) {
+    const kind = ctx.words[0];
+    if (kind !== "org") {
+        ctx.out("  usage: npx heedvane auth org   (reads the organization API key from stdin)");
+        return 2;
+    }
+    const key = (await ctx.readStdin()).trim();
+    if (key === "") {
+        ctx.out("  ✗ no key on stdin");
+        return 1;
+    }
+    const root = join(ctx.home, ".heed");
+    await withSignInChange(root, heedvaneConfigAt(root).url, () => saveCredential(root, kind, key));
+    ctx.out(`  ✓ ${kind} key saved to ~/.heed/credentials.json (mode 0600)`);
+    return 0;
+}
+/** `npx heedvane skills sync [--project]`: home skill dirs by default, the current project's with --project. */
+export async function cmdSkills(ctx) {
+    if (ctx.words[0] !== "sync") {
+        ctx.out("  usage: npx heedvane skills sync [--project]");
+        return 2;
+    }
+    const root = join(ctx.home, ".heed");
+    const backend = await backendAt(root, heedvaneConfigAt(root).url);
+    if (backend === null) {
+        ctx.out("  ✗ not signed in — run: npx heedvane login (or, headless: npx heedvane auth org < key-file)");
+        return 1;
+    }
+    try {
+        const synced = await syncApprovedSkills(backend, { root, base: ctx.project ? process.cwd() : ctx.home });
+        ctx.out(`  ✓ ${synced.installed.length} approved skill(s) installed${synced.installed.length > 0 ? `: ${synced.installed.join(", ")}` : ""}`);
+        if (synced.removed.length > 0)
+            ctx.out(`  ✓ no longer approved, removed: ${synced.removed.join(", ")}`);
+        return 0;
+    }
+    catch (err) {
+        ctx.out(`  ✗ skills sync failed: ${errorMessage(err)}`);
+        ctx.out("    the previous approved list (if any) is unchanged");
+        return 1;
+    }
+}

package/dist/commands/memory.d.ts

@@ -0,0 +1,10 @@
+export interface MemoryCommandContext {
+    home: string;
+    out: (line: string) => void;
+    /** The words after `memory`: the subcommand, then its arguments. */
+    words: string[];
+    /** The value after `flag` in the raw arguments, if any. */
+    flag: (name: string) => string | undefined;
+    cwd: string;
+}
+export declare function cmdMemory(ctx: MemoryCommandContext): Promise<number>;

package/dist/commands/memory.js

@@ -0,0 +1,106 @@
+/**
+ * `npx heedvane memory list | show | search`: the team memory's tree for agents without MCP, wrapping the
+ * same routes the MCP tools and the session-start table of contents use (src/memory/team-memory.ts). The
+ * repository is the current checkout's origin; a folder is passed exactly as `list` printed it.
+ */
+import { join } from "node:path";
+import { repoRemote } from "../backend/repo-remote.js";
+import { backendAt } from "../backend/credentials.js";
+import { heedvaneConfigAt } from "../heed-file.js";
+import { isRecord } from "../guards.js";
+import { askTeamMemory } from "../memory/team-memory.js";
+const USAGE = [
+    '  usage: npx heedvane memory list [folder] [--offset <n>]   browse the team memory of this checkout\'s repository',
+    "         npx heedvane memory show <id>                       read one memory",
+    '         npx heedvane memory search "<question>" [--folder <folder>]',
+];
+export async function cmdMemory(ctx) {
+    const [subcommand, ...rest] = ctx.words;
+    const argument = rest[0];
+    if (subcommand === "show" && argument !== undefined)
+        return ask(ctx, { action: "get", body: { id: argument }, print: showMemory, inRepository: false });
+    if (subcommand === "search" && argument !== undefined)
+        return ask(ctx, { action: "search", body: { query: argument, ...optional("folder", ctx.flag("--folder")) }, print: searchResult, inRepository: true });
+    if (subcommand === "list")
+        return ask(ctx, { action: "list", body: { ...optional("folder", argument), ...optional("offset", ctx.flag("--offset"), Number) }, print: (json, out) => listing(json, out, argument), inRepository: true });
+    for (const line of USAGE)
+        ctx.out(line);
+    return 2;
+}
+function optional(key, value, convert) {
+    return value === undefined || value === "" ? {} : { [key]: convert === undefined ? value : convert(value) };
+}
+async function ask(ctx, request) {
+    const gitOrigin = request.inRepository ? await repoRemote(ctx.cwd) : null;
+    if (gitOrigin === "") {
+        ctx.out("  ✗ not in a git checkout with an origin: team memory belongs to a repository");
+        return 1;
+    }
+    const root = join(ctx.home, ".heed");
+    const backend = await backendAt(root, heedvaneConfigAt(root).url);
+    if (backend === null) {
+        ctx.out("  ✗ not signed in — run: npx heedvane login (or, headless: npx heedvane auth org < key-file)");
+        return 1;
+    }
+    const answer = await askTeamMemory(backend, { action: request.action, body: gitOrigin === null ? request.body : { gitOrigin, ...request.body } });
+    if (answer.state === "unavailable") {
+        ctx.out(`  ✗ team memory is not available: ${answer.error}${answer.status === null ? "" : ` (${answer.status})`}`);
+        return 1;
+    }
+    request.print(answer.json, ctx.out);
+    return 0;
+}
+const text = (value) => (typeof value === "string" ? value : "");
+const day = (value) => text(value).slice(0, 10);
+const commit = (value) => (typeof value === "string" ? ` at ${value.slice(0, 7)}` : "");
+function memoryLine(memory) {
+    return `[${text(memory["id"])}] ${text(memory["title"])} · confirmed ${day(memory["validatedAt"])}${commit(memory["validatedCommitSha"])}`;
+}
+function records(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+function folderLine(folder) {
+    return `  ${text(folder["folder"])} (${String(folder["count"])})`;
+}
+function moreLine(shown, total, requested) {
+    return `  ${shown} of ${total} memories shown. More: npx heedvane memory list ${requested === undefined ? "" : `"${requested}" `}--offset ${shown}`;
+}
+const numberOr = (value, fallback) => (typeof value === "number" ? value : fallback);
+function listing(json, out, requested) {
+    const folders = records(json["folders"]);
+    const memories = records(json["memories"]);
+    const total = numberOr(json["total"], memories.length);
+    const where = text(json["folder"]) || "the top level";
+    if (folders.length === 0 && memories.length === 0)
+        return out(`  nothing in ${requested ?? where}`);
+    out(`  ${where}`);
+    for (const folder of folders)
+        out(folderLine(folder));
+    for (const memory of memories)
+        out(`  ${memoryLine(memory)}`);
+    const shown = numberOr(json["offset"], 0) + memories.length;
+    if (shown < total)
+        out(moreLine(shown, total, requested));
+    else if (memories.length > 0)
+        out(`  ${total} memories`);
+}
+function showMemory(json, out) {
+    const memory = isRecord(json["memory"]) ? json["memory"] : {};
+    out(`  ${memoryLine(memory)}`);
+    out(`  folder: ${text(memory["folder"])}   saved at ${text(memory["commitSha"]).slice(0, 7) || "an unrecorded commit"}`);
+    const paths = Array.isArray(memory["paths"]) ? memory["paths"].filter((path) => typeof path === "string") : [];
+    if (paths.length > 0)
+        out(`  files: ${paths.join(", ")}`);
+    out("");
+    out(text(memory["content"]));
+}
+function searchResult(json, out) {
+    const hits = records(json["memories"]);
+    if (hits.length === 0)
+        return out("  no memory matches");
+    for (const hit of hits) {
+        out(`  [${text(hit["id"])}] ${text(hit["title"])} (${typeof hit["score"] === "number" ? hit["score"].toFixed(2) : "?"}) · ${text(hit["folder"])} · confirmed ${day(hit["validatedAt"])}${commit(hit["validatedCommitSha"])}`);
+        out(text(hit["content"]));
+        out("");
+    }
+}

package/dist/config-doc.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Per-format parse / patch / serialize for agent config files.
+ *
+ * Formats:
+ *  - "json"     — strict JSON (JSON.parse), servers key `mcpServers`
+ *  - "jsonc"    — JSON with comments (jsonc-parser), style preserved via
+ *                 format edits; servers key `mcpServers`
+ *  - "toml"     — smol-toml parse/stringify, servers key `mcp_servers`
+ *  - "vscode"   — strict JSON, servers key `servers`
+ *  - "opencode" — strict JSON, servers key `mcp`
+ *
+ * A ParsedDoc carries the parsed value; for JSONC it also carries the original
+ * text so mutations can be applied as edits that preserve comments and the
+ * user's existing style. JSONC mutation MUST go through withServer /
+ * removeServer — mutating doc.value directly leaves the edit buffer stale.
+ */
+export type ConfigFormat = "json" | "jsonc" | "toml" | "vscode" | "opencode";
+/** Compat alias — A's plan/doctor/uninstall refer to the format type as DocFormat. */
+export type DocFormat = ConfigFormat;
+export interface ParsedDoc {
+    format: ConfigFormat;
+    value: Record<string, unknown>;
+    /** JSONC and TOML: current edit-buffer text (comments and style preserved). */
+    text?: string;
+    /** JSONC and TOML: whether any edit has been applied to the buffer. */
+    edited?: boolean;
+}
+/** Parse config text into a ParsedDoc. Throws ConfigParseError on malformed input. */
+export declare function parseDoc(text: string, format: ConfigFormat): ParsedDoc;
+/**
+ * Serialize a doc back to text.
+ * - JSON family: 2-space pretty JSON with trailing newline.
+ * - JSONC: if the doc carries an edit buffer (edited), return it verbatim —
+ *   comments and surrounding style preserved. If the doc was never edited and
+ *   `originalText` is given, return `originalText` unchanged (no semantic
+ *   change => no byte change). Otherwise fall back to pretty JSON.
+ * - TOML: the edit buffer when it decodes to the doc's value (comments preserved),
+ *   else smol-toml stringify.
+ */
+export declare function serializeDoc(doc: ParsedDoc, format: ConfigFormat, originalText?: string): string;
+/** The container key naming the document's own top level (Cursor's `version`), not a table inside it. */
+export declare const TOP_LEVEL = ".";
+/**
+ * Compat helper (A's API): read `doc[containerKey][entryName]` without the
+ * per-format servers-key machinery, or `doc[entryName]` for {@link TOP_LEVEL}.
+ * `undefined` when either level is missing or not a plain object.
+ */
+export declare function readEntry(doc: ParsedDoc, containerKey: string, entryName: string): unknown;
+/** The servers map of a doc, or undefined when absent. Throws ServersTableError when present but not an object. */
+export declare function getServers(doc: ParsedDoc, format: ConfigFormat, serversKey?: string): Record<string, unknown> | undefined;
+/** Set (or, with `undefined`, remove) one top-level key of a JSON or JSONC document, keeping JSONC comments. */
+export declare function withTopLevelKey(doc: ParsedDoc, edit: {
+    key: string;
+    value: unknown;
+}): ParsedDoc;
+/** Where a server entry lives and what to write there. */
+export interface ServerEdit {
+    serversKey: string;
+    name: string;
+    desired: unknown;
+}
+/** Names an existing server entry inside a doc. */
+export interface ServerRef {
+    serversKey: string;
+    name: string;
+}
+/**
+ * Set `servers[name] = desired`, creating the servers table when missing.
+ * For JSONC the change is applied as a format edit on the preserved text.
+ * Returns the same doc (mutated), for chaining.
+ */
+export declare function withServer(doc: ParsedDoc, format: ConfigFormat, edit: ServerEdit): ParsedDoc;
+/** A hooks entry we own: its command (Cursor's flat entry) or one of its group's commands carries the snippet marker. */
+export declare function isOurHookGroup(group: unknown): boolean;
+/**
+ * The value an entry should hold once ours is applied. A `hooks` event holds a list of
+ * groups shared with the user's own hooks: theirs are kept in order and ours replaced.
+ * A top-level version keeps a higher one already there.
+ */
+export declare function entryValue(containerKey: string, current: unknown, desired: unknown): unknown;
+/**
+ * Delete `servers[name]` when present. No-op when the table or the entry is
+ * absent. For JSONC the deletion is a style-preserving edit.
+ */
+export declare function removeServer(doc: ParsedDoc, format: ConfigFormat, ref: ServerRef): ParsedDoc;
+/**
+ * Deep-equal over sorted keys (key order ignored, array order preserved).
+ * Returns true when `a` and `b` are semantically the same config value.
+ */
+export declare function valuesEqual(a: unknown, b: unknown): boolean;
+/**
+ * Marker detection: does the doc carry a heedvane-managed entry? True when
+ * `name` is the reserved name or carries an identity marker, or when ANY
+ * entry in the servers table is marker-carrying (our entry may live under a
+ * user-chosen name). False when the doc has no heedvane entry.
+ */
+export declare function detectMarker(doc: ParsedDoc, format: ConfigFormat, ref: ServerRef): boolean;