heedvane 0.0.0-stage → 0.2.0

package/dist/listener/server.js

@@ -0,0 +1,251 @@
+import { createServer } from "node:http";
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import { endpointPath, readEndpoint } from "./endpoint.js";
+import { drainSpool } from "./spool.js";
+import { normalize } from "../events/normalize.js";
+import { errorMessage } from "../guards.js";
+/** Wire-protocol version stamped by installed dispatchers (`x-heed-hook-version`). */
+const WIRE_PROTOCOL_VERSION = 1;
+/** Agent ids accepted on `/hook/<agentId>`. */
+export const KNOWN_AGENTS = new Set([
+    "claude",
+    "codex",
+    "gemini",
+    "cursor",
+    "opencode",
+    "qwen-code",
+    "kimi",
+    "droid",
+    "antigravity",
+    "copilot_cli",
+    "windsurf",
+    "hermes",
+]);
+/** Request body cap: 5 MB. */
+export const MAX_BODY_BYTES = 5_242_880;
+/** Hard per-request timeout (slowloris guard): destroy the socket. */
+const REQUEST_TIMEOUT_MS = 5_000;
+/**
+ * Constant-time token comparison. Both sides are hashed first so the buffers
+ * always match in length (timingSafeEqual throws on length mismatch, and a
+ * length-leaking early return would defeat the point).
+ */
+export function safeTokenEqual(a, b) {
+    const da = createHash("sha256").update(a, "utf8").digest();
+    const db = createHash("sha256").update(b, "utf8").digest();
+    return timingSafeEqual(da, db);
+}
+class BodyTooLargeError extends Error {
+    constructor() {
+        super("request body exceeds the cap");
+        this.name = "BodyTooLargeError";
+    }
+}
+/**
+ * Read the full body, but only retain it while under the cap (we still drain
+ * the rest so the client's write side always completes, which keeps any HTTP
+ * client — fetch included — reliably receiving the 413 response).
+ */
+async function readBody(req) {
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of req) {
+        const buf = chunk;
+        size += buf.length;
+        if (size <= MAX_BODY_BYTES)
+            chunks.push(buf);
+    }
+    if (size > MAX_BODY_BYTES) {
+        throw new BodyTooLargeError();
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function sendJson(res, status, body) {
+    if (res.writableEnded || res.destroyed)
+        return;
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+const ROUTE_PATTERN = /^\/hook\/([A-Za-z0-9_-]+)$/;
+/** The route's agent id, or null after answering 404/405. */
+function routeAgent(req, res, agents) {
+    const route = ROUTE_PATTERN.exec(new URL(req.url ?? "/", "http://127.0.0.1").pathname);
+    if (route === null) {
+        sendJson(res, 404, { error: "not found" });
+        return null;
+    }
+    const agent = route[1];
+    if (req.method !== "POST") {
+        sendJson(res, 405, { error: "method not allowed; POST only" });
+        return null;
+    }
+    if (!agents.has(agent)) {
+        sendJson(res, 404, { error: `unknown agent route: /hook/${agent}` });
+        return null;
+    }
+    return agent;
+}
+/** Constant-time token check against endpoint.env (401 on mismatch or missing header). */
+function hasValidToken(req, token) {
+    const header = req.headers["x-heed-agent-hook-token"];
+    const provided = Array.isArray(header) ? header[0] : header;
+    return typeof provided === "string" && safeTokenEqual(provided, token);
+}
+/** Warn once per (agent, version) so stale installed scripts are diagnosable without dropping their data. */
+function warnOnVersionMismatch(req, deps, agent) {
+    const versionHeader = req.headers["x-heed-hook-version"];
+    const version = Array.isArray(versionHeader) ? versionHeader[0] : versionHeader;
+    if (version === String(WIRE_PROTOCOL_VERSION))
+        return;
+    const warnKey = `${agent}\u001f${version ?? "<missing>"}`;
+    if (deps.warned.has(warnKey))
+        return;
+    deps.warned.add(warnKey);
+    deps.log(`[heedvane] /hook/${agent}: hook version ${version ?? "<missing>"} ` +
+        `(expected ${WIRE_PROTOCOL_VERSION}); accepted — reinstall hooks via ` +
+        `"npx heedvane setup" if this persists`);
+}
+/** The request body under the cap, or null after answering 413. Non-cap failures propagate. */
+async function readBodyUnderCap(req, res) {
+    const timer = setTimeout(() => req.socket.destroy(), REQUEST_TIMEOUT_MS);
+    try {
+        return await readBody(req);
+    }
+    catch (err) {
+        if (err instanceof BodyTooLargeError) {
+            sendJson(res, 413, { error: `body exceeds ${MAX_BODY_BYTES} bytes` });
+            return null;
+        }
+        // Socket destroyed (timeout/slowloris) or client aborted — nothing to answer.
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The parsed JSON body, or null after answering 400 (unparseable or not an object). */
+function parseJsonObject(bodyText, res) {
+    let body;
+    try {
+        body = JSON.parse(bodyText);
+    }
+    catch {
+        sendJson(res, 400, { error: "body is not valid JSON" });
+        return null;
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        sendJson(res, 400, { error: "body must be a JSON object" });
+        return null;
+    }
+    return body;
+}
+/** Last-resort responder: an async failure must not hang or crash the process. */
+function internalErrorResponder(res) {
+    return () => {
+        sendJson(res, 500, { error: "internal error" });
+    };
+}
+async function handleRequest(req, res, deps) {
+    const agent = routeAgent(req, res, deps.agents);
+    if (agent === null)
+        return;
+    if (!hasValidToken(req, deps.token)) {
+        sendJson(res, 401, { error: "invalid or missing x-heed-agent-hook-token" });
+        return;
+    }
+    // Wire-protocol version: accept anything, but surface stale installed scripts.
+    warnOnVersionMismatch(req, deps, agent);
+    // Slowloris guard: if the body hasn't fully arrived within 5 s, destroy the
+    // socket. Node's requestTimeout/headersTimeout (set below) cover stalls
+    // before the request handler even fires.
+    const bodyText = await readBodyUnderCap(req, res);
+    if (bodyText === null)
+        return;
+    const body = parseJsonObject(bodyText, res);
+    if (body === null)
+        return;
+    // Normalize at the door: every accepted event leaves as the canonical
+    // envelope — one taxonomy for all ingest paths (listener, spool replay).
+    const envelope = normalize(agent, body, { id: eventId(req.headers["x-heed-event-id"]) });
+    // The dispatcher prints this body as the agent's hook output; `{}` lets the agent continue.
+    sendJson(res, 200, (await deps.onEvent({ agent, body, envelope, headers: req.headers })) ?? {});
+}
+/**
+ * Start the loopback hook listener: binds 127.0.0.1 only (never 0.0.0.0),
+ * serves POST /hook/<agentId>, auths via x-heed-agent-hook-token against
+ * endpoint.env. Refuses to start (with remediation) when endpoint.env is
+ * missing or has no TOKEN.
+ */
+export async function startListener(options) {
+    const endpoint = await readEndpoint(options.root);
+    if (endpoint === null) {
+        throw new Error(`No endpoint.env at ${endpointPath(options.root)} — the listener has no port/token to serve. ` +
+            `Remediation: run "npx heedvane setup" to write ${endpointPath(options.root)} ` +
+            `with PORT and TOKEN lines (mode 0600), then start the listener again.`);
+    }
+    if (!endpoint.token) {
+        throw new Error(`endpoint.env at ${endpointPath(options.root)} has no TOKEN — every hook dispatcher would 401. ` +
+            `Remediation: run "npx heedvane setup" to (re)issue the listener token, ` +
+            `or add a HEED_AGENT_HOOK_TOKEN=<random hex> line to ${endpointPath(options.root)}.`);
+    }
+    const log = options.log ?? ((message) => console.log(message));
+    const agents = options.knownAgents ?? KNOWN_AGENTS;
+    const deps = {
+        agents,
+        token: endpoint.token,
+        onEvent: options.onEvent,
+        log,
+        warned: new Set(),
+    };
+    const server = createServer((req, res) => {
+        handleRequest(req, res, deps).catch(internalErrorResponder(res));
+    });
+    // Node-level slowloris hardening (covers stalls before the request handler
+    // fires); requestTimeout must be larger than headersTimeout.
+    server.requestTimeout = REQUEST_TIMEOUT_MS;
+    server.headersTimeout = REQUEST_TIMEOUT_MS - 500;
+    await new Promise((resolve, reject) => {
+        const onListenError = (err) => reject(err);
+        server.once("error", onListenError);
+        server.listen(endpoint.port, "127.0.0.1", () => {
+            server.off("error", onListenError);
+            server.on("error", (err) => log(`[heedvane] listener error: ${err.message}`));
+            resolve();
+        });
+    });
+    const address = server.address();
+    const port = address !== null && typeof address === "object" ? address.port : endpoint.port;
+    // Events the dispatchers spooled while no listener was up enter through the same door.
+    // A replay that fails (a full disk) leaves the spool file whole for the next start and never keeps the
+    // listener, and with it the deny rules, from starting.
+    const replayed = await drainSpool(options.root, async (spooled) => {
+        let body;
+        try {
+            body = JSON.parse(spooled.payload);
+        }
+        catch {
+            log(`[heedvane] dropped a spooled ${spooled.source} event whose payload is not JSON`);
+            return;
+        }
+        if (body === null || typeof body !== "object" || Array.isArray(body))
+            return;
+        const envelope = normalize(spooled.source, body, { receivedAt: spooledTime(spooled.receivedAt), id: eventId(spooled.id) });
+        await options.onEvent({ agent: spooled.source, body, envelope, headers: {}, replayed: true });
+    }).catch((err) => {
+        log(`[heedvane] could not replay the spooled events (kept for the next start): ${errorMessage(err)}`);
+        return 0;
+    });
+    return { server, port, replayed };
+}
+/** The dispatcher's event id when it is a plausible one, else a fresh one (scripts older than ids). */
+function eventId(value) {
+    return typeof value === "string" && /^[A-Za-z0-9-]{8,64}$/.test(value) ? value : randomUUID();
+}
+/** When the dispatcher spooled the event, or now when its stamp is not a date. */
+function spooledTime(value) {
+    return typeof value === "string" && !Number.isNaN(Date.parse(value)) ? new Date(value).toISOString() : undefined;
+}

package/dist/listener/spool.d.ts

@@ -0,0 +1,28 @@
+/**
+ * One spooled hook event, exactly as the dispatcher script (`spool_hook_event` in
+ * dispatchers/posix.ts, the only writer) appends it: `payload` is the raw hook JSON text
+ * the agent piped in, `source` the agent id. Cap and TTL are enforced by that writer.
+ */
+export interface SpooledEvent {
+    paneKey: string;
+    tabId: string;
+    worktreeId: string;
+    launchToken: string;
+    source: string;
+    receivedAt: string;
+    payload: string;
+    /** The event's unique id (absent in lines from scripts older than ids). */
+    id?: string;
+}
+/** Directory under the heed root that holds per-pane spool files. */
+export declare function spoolDir(root: string): string;
+/** A pane spool file, or one a drain claimed (renamed away from the dispatcher) and has not finished. */
+export declare function isPaneSpoolFile(name: string): boolean;
+/**
+ * Drain every pane spool file: claim it by renaming it, so the dispatcher's next append starts a fresh
+ * file and none is lost between reading and emptying; parse each line as JSON and hand it to `onEvent`;
+ * then delete the claimed file. A claimed file a failed or killed drain left is drained again by the
+ * next call. Lines that fail to parse are skipped (a torn append from a killed dispatcher). Returns the
+ * number of events delivered.
+ */
+export declare function drainSpool(root: string, onEvent: (event: SpooledEvent) => void | Promise<void>): Promise<number>;

package/dist/listener/spool.js

@@ -0,0 +1,60 @@
+import { readdir, readFile, rename, unlink } from "node:fs/promises";
+import { join } from "node:path";
+/** Directory under the heed root that holds per-pane spool files. */
+export function spoolDir(root) {
+    return join(root, "spool");
+}
+/** One spool line, or null for a torn append from a killed dispatcher (dropped by design). */
+function parseSpoolLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+}
+/** A pane spool file, or one a drain claimed (renamed away from the dispatcher) and has not finished. */
+export function isPaneSpoolFile(name) {
+    return name.startsWith("pane-") && (name.endsWith(".jsonl") || name.includes(".jsonl.claimed-"));
+}
+/**
+ * Drain every pane spool file: claim it by renaming it, so the dispatcher's next append starts a fresh
+ * file and none is lost between reading and emptying; parse each line as JSON and hand it to `onEvent`;
+ * then delete the claimed file. A claimed file a failed or killed drain left is drained again by the
+ * next call. Lines that fail to parse are skipped (a torn append from a killed dispatcher). Returns the
+ * number of events delivered.
+ */
+export async function drainSpool(root, onEvent) {
+    const dir = spoolDir(root);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return 0;
+        throw err;
+    }
+    let drained = 0;
+    for (const entry of entries.sort()) {
+        if (!isPaneSpoolFile(entry))
+            continue;
+        const claimed = entry.endsWith(".jsonl") ? `${entry}.claimed-${Date.now()}-${process.pid}` : entry;
+        const filePath = join(dir, claimed);
+        if (claimed !== entry)
+            await rename(join(dir, entry), filePath);
+        const content = await readFile(filePath, "utf8");
+        for (const line of content.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            const event = parseSpoolLine(trimmed);
+            if (event === null)
+                continue;
+            await onEvent(event);
+            drained += 1;
+        }
+        await unlink(filePath);
+    }
+    return drained;
+}

package/dist/mcp-server.d.ts

@@ -0,0 +1,9 @@
+export interface McpIo {
+    write: (line: string) => void;
+    log: (line: string) => void;
+}
+export declare function statusText(): Promise<string>;
+/** Entry point for the `mcp` subcommand. */
+export declare function runMcpStdio(io: Pick<McpIo, "write"> & {
+    log?: (line: string) => void;
+}): void;

package/dist/mcp-server.js

@@ -0,0 +1,187 @@
+/**
+ * `npx heedvane mcp` — the MCP stdio server stub the installers register.
+ * v1 exposes two tools (status, doctor) over line-delimited JSON-RPC.
+ */
+import { createInterface } from "node:readline";
+import { runDoctor } from "./doctor.js";
+import { cmdMemory } from "./commands/memory.js";
+const MCP_SERVER_INFO = { name: "heedvane-hooks", version: "0.1.0" };
+const TOOLS = [
+    {
+        name: "heedvane_status",
+        description: "Report the live heedvane hook installation state for this machine (agents, skill, listener).",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "heedvane_doctor",
+        description: "Run the scoped heedvane doctor and return its checks with remediations.",
+        inputSchema: {
+            type: "object",
+            properties: { clients: { type: "array", items: { type: "string" } } },
+        },
+    },
+    {
+        name: "heedvane_memory_list",
+        description: "List team memory folders and entries for the current repository.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                folder: { type: "string", description: "Optional folder name to filter by." },
+                cwd: { type: "string", description: "Optional repository checkout path." },
+            },
+        },
+    },
+    {
+        name: "heedvane_memory_show",
+        description: "Read the full markdown content of a team memory entry by id.",
+        inputSchema: {
+            type: "object",
+            required: ["id"],
+            properties: {
+                id: { type: "string", description: "The team memory id." },
+                cwd: { type: "string", description: "Optional repository checkout path." },
+            },
+        },
+    },
+    {
+        name: "heedvane_memory_search",
+        description: "Semantically search team memory for the current repository.",
+        inputSchema: {
+            type: "object",
+            required: ["query"],
+            properties: {
+                query: { type: "string", description: "The question or search query." },
+                folder: { type: "string", description: "Optional folder name to restrict search." },
+                cwd: { type: "string", description: "Optional repository checkout path." },
+            },
+        },
+    },
+];
+/** Run a team memory command and return its collected lines. */
+async function runMemoryTool(words, flags, cwd) {
+    const lines = [];
+    await cmdMemory({
+        home: process.env.HEED_HOME ?? homeDir(),
+        out: (line) => lines.push(line),
+        words,
+        flag: (name) => flags[name],
+        cwd: typeof cwd === "string" && cwd.trim() !== "" ? cwd : process.cwd(),
+    });
+    return lines.join("\n");
+}
+function handleMemoryToolCall(name, args, reply) {
+    if (name === "heedvane_memory_list") {
+        const folder = typeof args.folder === "string" && args.folder.trim() !== "" ? [args.folder.trim()] : [];
+        void runMemoryTool(["list", ...folder], {}, args.cwd).then((text) => reply(textContent(text)));
+        return true;
+    }
+    if (name === "heedvane_memory_show") {
+        const id = typeof args.id === "string" ? args.id.trim() : "";
+        void runMemoryTool(["show", ...(id ? [id] : [])], {}, args.cwd).then((text) => reply(textContent(text)));
+        return true;
+    }
+    if (name === "heedvane_memory_search") {
+        const query = typeof args.query === "string" ? args.query.trim() : "";
+        const folder = typeof args.folder === "string" && args.folder.trim() !== "" ? args.folder.trim() : undefined;
+        void runMemoryTool(["search", ...(query ? [query] : [])], { "--folder": folder }, args.cwd).then((text) => reply(textContent(text)));
+        return true;
+    }
+    return false;
+}
+/** The tools/call branch: reply with the tool's text content, or a unknown-tool error. */
+function handleToolCall(msg, reply, fail) {
+    const name = msg.params?.name;
+    const args = msg.params?.arguments ?? {};
+    if (name === "heedvane_status") {
+        void statusText().then((text) => reply(textContent(text)));
+        return;
+    }
+    if (name === "heedvane_doctor") {
+        const clients = args.clients;
+        const input = { home: process.env.HEED_HOME ?? homeDir(), env: process.env };
+        if (Array.isArray(clients))
+            input.clients = clients.map(String);
+        void runDoctor(input).then((report) => reply(textContent(JSON.stringify(report, null, 2))));
+        return;
+    }
+    if (handleMemoryToolCall(name, args, reply))
+        return;
+    fail(-32602, `unknown tool: ${String(name)}`);
+}
+function handleRpc(msg, io) {
+    const { method, id } = msg;
+    if (!method || id === undefined)
+        return; // notification: ignore silently
+    const reply = (result) => io.write(JSON.stringify({ jsonrpc: "2.0", id, result }));
+    const fail = (code, message) => io.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }));
+    switch (method) {
+        case "initialize":
+            reply({ protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: MCP_SERVER_INFO });
+            return;
+        case "tools/list":
+            reply({ tools: TOOLS });
+            return;
+        case "tools/call":
+            handleToolCall(msg, reply, fail);
+            return;
+        default:
+            fail(-32601, `method not supported: ${method}`);
+    }
+}
+function textContent(text) {
+    return { content: [{ type: "text", text }] };
+}
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { HeedStateCorruptError, readState } from "./state.js";
+import { readEndpoint } from "./listener/endpoint.js";
+function homeDir() {
+    return homedir();
+}
+export async function statusText() {
+    const home = process.env.HEED_HOME ?? homeDir();
+    const root = join(home, ".heed");
+    const lines = [`heedvane hooks status (home: ${home})`];
+    try {
+        const state = await readState(root);
+        if (state !== null) {
+            const skill = state.skill?.digest.slice(0, 12) ?? "not installed";
+            lines.push(`  state.json: ok (protocol v${state.protocolVersion}, skill ${skill})`);
+        }
+        else {
+            lines.push("  state.json: absent (run npx heedvane init)");
+        }
+    }
+    catch (error) {
+        if (!(error instanceof HeedStateCorruptError))
+            throw error;
+        lines.push(`  state.json: ${error.message}`);
+    }
+    const endpoint = await readEndpoint(root);
+    lines.push(`  listener: ${endpoint ? `endpoint.env present (port ${endpoint.port})` : "not configured — events spool to ~/.heed/spool"}`);
+    lines.push("  next: npx heedvane doctor for scoped checks");
+    return lines.join("\n");
+}
+/** One stdin line → one RPC dispatch. A blank or unparseable line never crashes the host's transport. */
+function dispatchLine(line, io) {
+    const trimmed = line.trim();
+    if (trimmed === "")
+        return;
+    try {
+        handleRpc(JSON.parse(trimmed), io);
+    }
+    catch {
+        return; // unparseable line: ignore (never crash the host's transport)
+    }
+}
+/** Entry point for the `mcp` subcommand. */
+export function runMcpStdio(io) {
+    const log = io.log ?? (() => { });
+    const rl = createInterface({ input: process.stdin });
+    rl.on("line", (line) => {
+        dispatchLine(line, { write: io.write, log });
+    });
+    rl.on("close", () => {
+        log("heedvane mcp: stdin closed");
+    });
+}

package/dist/mcp.d.ts

@@ -0,0 +1,57 @@
+/**
+ * MCP registration entry builder per client.
+ *
+ * The heedvane MCP server is the universal integration channel — and the only
+ * policy channel for agents with no native hooks (Warp). Entries are stdio
+ * commands (`npx heedvane mcp`); an `--http` mode may be added later
+ * without changing the shape of these builders.
+ *
+ * Identity: uninstall and marker detection recognize our entries by the
+ * identity markers below (today's `npx -y heedvane mcp` args, plus the
+ * scoped and `heedvane-hooks` names development installs wrote), or by the
+ * reserved entry name `heedvane`.
+ */
+/** Reserved server entry name. Presence of this NAME alone marks the entry ours. */
+export declare const HEEDVANE_SERVER_NAME = "heedvane";
+/**
+ * Identity markers: an entry whose command/args contain any of these strings
+ * is a heedvane-managed entry, whatever name it is registered under. These are
+ * the names development builds wrote; today's entry is recognized by its whole
+ * argument list ({@link MCP_ENTRY_ARGS}), since the bare package name would
+ * also match a path like `~/Projects/heedvane`.
+ */
+export declare const IDENTITY_MARKERS: readonly ["@heedvane/hooks", "heedvane-hooks"];
+/** Uninstall/detection marker for inline dispatcher snippets (hooks configs). */
+export declare const SNIPPET_MARKER = "heedvane-agent-hook-form";
+/** Args of the stdio MCP entry (command is always `npx`). */
+export declare const MCP_ENTRY_ARGS: string[];
+export interface McpServerEntry {
+    command: string;
+    args: string[];
+    [key: string]: unknown;
+}
+/** The stdio MCP entry, for JSON-family configs (`mcpServers` / `servers` / `mcp`). */
+export declare function mcpEntry(): McpServerEntry;
+/**
+ * The stdio MCP entry for TOML configs. Codex reads `~/.codex/config.toml`
+ * where servers are `mcp_servers.<name>` and a slow `npx` cold start needs an
+ * explicit generous startup timeout.
+ */
+export declare function mcpEntryForToml(): McpServerEntry;
+/** Per-client desired entry. Only Codex (TOML) carries the startup timeout. */
+export declare function desiredServer(clientId: string): McpServerEntry;
+/** Warp's MCP config is project-level and approval-gated. */
+export declare const WARP_MCP_RELATIVE_PATH = ".warp/.mcp.json";
+/**
+ * Honest limitation surfaced by init/doctor for Warp. Warp has no native
+ * hooks and its MCP support is project-scoped and import-gated: the user must
+ * approve the import in Warp, per project, before the server activates.
+ * Policies therefore arrive via MCP tools, not hooks.
+ */
+export declare const WARP_MCP_LIMITATION: string;
+/**
+ * Is this server entry a heedvane-managed one? True when the entry NAME is
+ * the reserved `heedvane` name, or when the entry's command/args carry an
+ * identity marker. Used by detectMarker and doctor.
+ */
+export declare function isHeedvaneEntry(name: string, entry: unknown): boolean;

package/dist/mcp.js

@@ -0,0 +1,83 @@
+/**
+ * MCP registration entry builder per client.
+ *
+ * The heedvane MCP server is the universal integration channel — and the only
+ * policy channel for agents with no native hooks (Warp). Entries are stdio
+ * commands (`npx heedvane mcp`); an `--http` mode may be added later
+ * without changing the shape of these builders.
+ *
+ * Identity: uninstall and marker detection recognize our entries by the
+ * identity markers below (today's `npx -y heedvane mcp` args, plus the
+ * scoped and `heedvane-hooks` names development installs wrote), or by the
+ * reserved entry name `heedvane`.
+ */
+/** Reserved server entry name. Presence of this NAME alone marks the entry ours. */
+export const HEEDVANE_SERVER_NAME = "heedvane";
+/**
+ * Identity markers: an entry whose command/args contain any of these strings
+ * is a heedvane-managed entry, whatever name it is registered under. These are
+ * the names development builds wrote; today's entry is recognized by its whole
+ * argument list ({@link MCP_ENTRY_ARGS}), since the bare package name would
+ * also match a path like `~/Projects/heedvane`.
+ */
+export const IDENTITY_MARKERS = ["@heedvane/hooks", "heedvane-hooks"];
+/** Uninstall/detection marker for inline dispatcher snippets (hooks configs). */
+export const SNIPPET_MARKER = "heedvane-agent-hook-form";
+/** The npm package name entries carry; marker + entry builder use it. */
+const MCP_ENTRY_COMMAND = "heedvane";
+/** Args of the stdio MCP entry (command is always `npx`). */
+export const MCP_ENTRY_ARGS = ["-y", MCP_ENTRY_COMMAND, "mcp"];
+/** The stdio MCP entry, for JSON-family configs (`mcpServers` / `servers` / `mcp`). */
+export function mcpEntry() {
+    return { command: "npx", args: [...MCP_ENTRY_ARGS] };
+}
+/**
+ * The stdio MCP entry for TOML configs. Codex reads `~/.codex/config.toml`
+ * where servers are `mcp_servers.<name>` and a slow `npx` cold start needs an
+ * explicit generous startup timeout.
+ */
+export function mcpEntryForToml() {
+    return { command: "npx", args: [...MCP_ENTRY_ARGS], startup_timeout_sec: 30 };
+}
+/** Per-client desired entry. Only Codex (TOML) carries the startup timeout. */
+export function desiredServer(clientId) {
+    return clientId === "codex" ? mcpEntryForToml() : mcpEntry();
+}
+/** Warp's MCP config is project-level and approval-gated. */
+export const WARP_MCP_RELATIVE_PATH = ".warp/.mcp.json";
+/**
+ * Honest limitation surfaced by init/doctor for Warp. Warp has no native
+ * hooks and its MCP support is project-scoped and import-gated: the user must
+ * approve the import in Warp, per project, before the server activates.
+ * Policies therefore arrive via MCP tools, not hooks.
+ */
+export const WARP_MCP_LIMITATION = "Warp limitation: Warp has no native hooks support, and its MCP servers are project-scoped and " +
+    "approval-gated. Heedvane writes a project-level .warp/.mcp.json for the current project only; " +
+    "you must approve the heedvane MCP import inside Warp (Settings > MCP) before it activates, and " +
+    "repeat that approval in every project you use it in. Hooks are unsupported in Warp — policies " +
+    "arrive via MCP tools once the server import is approved.";
+/**
+ * Does this entry's command/args carry a heedvane identity marker? This is
+ * the STRICT check used by uninstall: an entry is only removed when its
+ * command/args prove it is ours. A name match without the marker is a
+ * renamed/replaced entry and is left alone.
+ */
+function hasHeedvaneMarker(entry) {
+    if (entry === null || typeof entry !== "object")
+        return false;
+    const e = entry;
+    const command = typeof e.command === "string" ? e.command : "";
+    const args = Array.isArray(e.args) ? e.args.filter((a) => typeof a === "string") : [];
+    const haystack = [command, ...args].join(" ");
+    return haystack.includes(MCP_ENTRY_ARGS.join(" ")) || IDENTITY_MARKERS.some((m) => haystack.includes(m));
+}
+/**
+ * Is this server entry a heedvane-managed one? True when the entry NAME is
+ * the reserved `heedvane` name, or when the entry's command/args carry an
+ * identity marker. Used by detectMarker and doctor.
+ */
+export function isHeedvaneEntry(name, entry) {
+    if (name === HEEDVANE_SERVER_NAME)
+        return true;
+    return hasHeedvaneMarker(entry);
+}