heedvane 0.2.0 → 0.3.3

package/dist/heed-file.d.ts

@@ -27,9 +27,19 @@ export interface HeedSkillsConfig {
     /** No synced approved list, or no listener to check it: let the skill run with a warning, or deny it. */
     whenUnknown: "allow" | "deny";
 }
+/**
+ * What leaves this machine (the installer and data modes proposal, "Proposed data modes"). `look-but-dont-keep`:
+ * Heedvane's guardrail checks read the prompt or tool call and keep only the verdict. `metrics-only`: only counts and
+ * names leave; the organization's fixed rules still run here, Heedvane's own checks and team memory do not.
+ */
+export declare const DATA_MODES: readonly ["look-but-dont-keep", "metrics-only"];
+export type DataMode = (typeof DATA_MODES)[number];
 /** The Heedvane backend the listener asks for steering, approved skills and memory. */
 export interface HeedvaneConfig {
     url: string;
+    /** The organization `connect --org` named: Heedvane's MCP connection URL carries it. */
+    org?: string;
+    dataMode: DataMode;
     steering: boolean;
     memory: boolean;
     skills: HeedSkillsConfig;
@@ -47,7 +57,7 @@ export interface HeedFile {
  * The commented control file written by `npx heedvane init`.
  * Kept loadable: loadHeedFile(DEFAULT_HEED_YAML_TEMPLATE) yields every default.
  */
-export declare const DEFAULT_HEED_YAML_TEMPLATE = "# ~/.heed/heed.yaml \u2014 Heedvane agent hooks control file (v1)\nschemaVersion: v1\n\n# Where managed scripts and spool live. Default below; one install per machine.\nroot: ~/.heed\n\n# The hook listener (Orca's pattern): loopback HTTP, token-authed, per-agent routes.\nlistener:\n  port: 0            # 0 = pick a free port at first start, persist to endpoint.env\n  spool: true        # spool to disk when listener is unreachable (5 MB cap, 7-day TTL)\n\n# Which agents to manage. `auto` = every detected agent on the machine.\nagents: auto        # or an explicit list: [claude, codex, warp]\n\n# Which integrations to install per agent where supported.\ninstall:\n  hooks: true       # native hook config injection (skipped where the agent has none)\n  skill: true       # heedvane-hooks skill bundle -> ~/.agents/skills/heedvane-hooks/\n  mcp: true         # heedvane MCP server registration (universal fallback, incl. Warp)\n\n# Session gating (Orca's env-gated dispatcher pattern).\ngating:\n  mode: always      # always = every session; pane = only sessions launched with HEED_SESSION env\n\n# The Heedvane backend (credentials: npx heedvane auth, stored in ~/.heed/credentials.json).\nheedvane:\n  url: https://app.heedvane.com\n  steering: true      # ask the organization's steering rules before tool calls, prompts and stops\n  memory: true        # add your private memories (~/.heed/memory, local only) at session start\n  skills:\n    enforce: true     # deny skills that are not on the organization's approved list\n    strict: false     # also require the local SKILL.md to match the approved revision\n    whenUnknown: allow  # no synced list (run npx heedvane skills sync) or listener down: allow or deny\n";
+export declare const DEFAULT_HEED_YAML_TEMPLATE = "# ~/.heed/heed.yaml \u2014 Heedvane agent hooks control file (v1)\nschemaVersion: v1\n\n# Where managed scripts and spool live. Default below; one install per machine.\nroot: ~/.heed\n\n# The hook listener (Orca's pattern): loopback HTTP, token-authed, per-agent routes.\nlistener:\n  port: 0            # 0 = pick a free port at first start, persist to endpoint.env\n  spool: true        # spool to disk when listener is unreachable (5 MB cap, 7-day TTL)\n\n# Which agents to manage. `auto` = every detected agent on the machine.\nagents: auto        # or an explicit list: [claude, codex, warp]\n\n# Which integrations to install per agent where supported.\ninstall:\n  hooks: true       # native hook config injection (skipped where the agent has none)\n  skill: true       # heedvane-hooks skill bundle -> ~/.agents/skills/heedvane-hooks/\n  mcp: true         # heedvane MCP server registration (universal fallback, incl. Warp)\n\n# Session gating (Orca's env-gated dispatcher pattern).\ngating:\n  mode: always      # always = every session; pane = only sessions launched with HEED_SESSION env\n\n# The Heedvane backend (credentials: npx heedvane auth, stored in ~/.heed/credentials.json).\nheedvane:\n  url: https://app.heedvane.com\n  dataMode: look-but-dont-keep  # what leaves this machine: look-but-dont-keep (checks read prompts and tool calls, keep only verdicts) or metrics-only (only counts and names)\n  steering: true      # ask the organization's steering rules before tool calls, prompts and stops\n  memory: true        # add your private memories (~/.heed/memory, local only) at session start\n  skills:\n    enforce: true     # deny skills that are not on the organization's approved list\n    strict: false     # also require the local SKILL.md to match the approved revision\n    whenUnknown: allow  # no synced list (run npx heedvane skills sync) or listener down: allow or deny\n";
 /**
  * Parse and validate a heed.yaml document, returning the fully normalized file.
  * Throws {@link HeedFileError} (message prefixed "invalid heed.yaml:") on any problem:
@@ -55,6 +65,8 @@ export declare const DEFAULT_HEED_YAML_TEMPLATE = "# ~/.heed/heed.yaml \u2014 He
  * (top-level or nested), or wrong-typed values.
  */
 export declare function loadHeedFile(text: string): HeedFile;
+/** `text` with each `[path, value]` written in place; the file's comments stay. Validate with {@link loadHeedFile}. */
+export declare function withSettings(text: string, settings: ReadonlyArray<readonly [string[], unknown]>): string;
 /** `text` with `heedvane.url` set to `url` (`connect --server`); the file's comments stay. Validate with {@link loadHeedFile}. */
 export declare function withServerUrl(text: string, url: string): string;
 /** What the interactive installer asks: which agents, which integrations, and which Heedvane features. */
@@ -62,6 +74,7 @@ export interface InstallChoices {
     /** Chosen agent ids, or "auto" for every detected agent. */
     agents: "auto" | string[];
     install: HeedInstallConfig;
+    dataMode: DataMode;
     steering: boolean;
     memory: boolean;
     skillChecks: boolean;

package/dist/heed-file.js

@@ -3,6 +3,12 @@ import { join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { isScalar, parse, parseDocument } from "yaml";
 import { errorMessage, isRecord } from "./guards.js";
+/**
+ * What leaves this machine (the installer and data modes proposal, "Proposed data modes"). `look-but-dont-keep`:
+ * Heedvane's guardrail checks read the prompt or tool call and keep only the verdict. `metrics-only`: only counts and
+ * names leave; the organization's fixed rules still run here, Heedvane's own checks and team memory do not.
+ */
+export const DATA_MODES = ["look-but-dont-keep", "metrics-only"];
 /** Error raised for any invalid heed.yaml. The message is user-facing: keep it precise. */
 class HeedFileError extends Error {
     constructor(message) {
@@ -50,6 +56,7 @@ gating:
 # The Heedvane backend (credentials: npx heedvane auth, stored in ~/.heed/credentials.json).
 heedvane:
   url: https://app.heedvane.com
+  dataMode: look-but-dont-keep  # what leaves this machine: look-but-dont-keep (checks read prompts and tool calls, keep only verdicts) or metrics-only (only counts and names)
   steering: true      # ask the organization's steering rules before tool calls, prompts and stops
   memory: true        # add your private memories (~/.heed/memory, local only) at session start
   skills:
@@ -165,12 +172,29 @@ function validateSkills(raw) {
     }
     return out;
 }
+/** `heedvane.org` and `heedvane.dataMode`, when set. */
+function validateOrgAndDataMode(map) {
+    const out = {};
+    const { org, dataMode } = map;
+    if (org !== undefined) {
+        if (typeof org !== "string" || org.trim() === "")
+            throw new HeedFileError(`"heedvane.org" must be a non-empty string, got ${describeType(org)}`);
+        out.org = org.trim();
+    }
+    if (dataMode !== undefined) {
+        const known = DATA_MODES.find((mode) => mode === dataMode);
+        if (known === undefined)
+            throw new HeedFileError(`"heedvane.dataMode" must be one of ${DATA_MODES.join(", ")}, got ${JSON.stringify(dataMode)}`);
+        out.dataMode = known;
+    }
+    return out;
+}
 function validateHeedvane(raw) {
-    const out = { url: "https://app.heedvane.com", steering: true, memory: true, skills: validateSkills(undefined) };
+    const out = { url: "https://app.heedvane.com", dataMode: "look-but-dont-keep", steering: true, memory: true, skills: validateSkills(undefined) };
     if (raw === undefined)
         return out;
     const map = expectMapping(raw, "heedvane");
-    rejectUnknownKeys(map, ["url", "steering", "memory", "skills"], "heedvane");
+    rejectUnknownKeys(map, ["url", "org", "dataMode", "steering", "memory", "skills"], "heedvane");
     const url = map["url"];
     if (url !== undefined) {
         if (typeof url !== "string" || !URL.canParse(url) || !/^https?:$/.test(new URL(url).protocol)) {
@@ -178,6 +202,7 @@ function validateHeedvane(raw) {
         }
         out.url = url.replace(/\/+$/, "");
     }
+    Object.assign(out, validateOrgAndDataMode(map));
     if (map["steering"] !== undefined)
         out.steering = expectBool(map["steering"], "heedvane.steering");
     if (map["memory"] !== undefined)
@@ -225,36 +250,34 @@ export function loadHeedFile(text) {
         heedvane: validateHeedvane(raw["heedvane"]),
     };
 }
-/** `text` with `heedvane.url` set to `url` (`connect --server`); the file's comments stay. Validate with {@link loadHeedFile}. */
-export function withServerUrl(text, url) {
+/** `text` with each `[path, value]` written in place; the file's comments stay. Validate with {@link loadHeedFile}. */
+export function withSettings(text, settings) {
     const document = parseDocument(text);
-    const current = document.getIn(["heedvane", "url"], true);
-    if (isScalar(current))
-        current.value = url;
-    else
-        document.setIn(["heedvane", "url"], url);
+    for (const [path, value] of settings) {
+        const current = document.getIn(path, true);
+        if (isScalar(current) && typeof value !== "object")
+            current.value = value;
+        else
+            document.setIn(path, value);
+    }
     return String(document);
 }
+/** `text` with `heedvane.url` set to `url` (`connect --server`); the file's comments stay. Validate with {@link loadHeedFile}. */
+export function withServerUrl(text, url) {
+    return withSettings(text, [[["heedvane", "url"], url]]);
+}
 /** `text` with the installer's choices written into the fields that already hold them; the file's comments stay. */
 export function withInstallChoices(text, choices) {
-    const document = parseDocument(text);
-    const fields = [
+    return withSettings(text, [
         [["agents"], choices.agents],
         [["install", "hooks"], choices.install.hooks],
         [["install", "skill"], choices.install.skill],
         [["install", "mcp"], choices.install.mcp],
+        [["heedvane", "dataMode"], choices.dataMode],
         [["heedvane", "steering"], choices.steering],
         [["heedvane", "memory"], choices.memory],
         [["heedvane", "skills", "enforce"], choices.skillChecks],
-    ];
-    for (const [path, value] of fields) {
-        const current = document.getIn(path, true);
-        if (isScalar(current) && typeof value !== "object")
-            current.value = value;
-        else
-            document.setIn(path, value);
-    }
-    return String(document);
+    ]);
 }
 /** Keys earlier versions wrote into heed.yaml that nothing reads any more (policies are assigned on the server). */
 const RETIRED_KEYS = [["heedvane", "steeringTimeoutMs"], ["policy"]];

package/dist/installer.d.ts

@@ -1,5 +1,5 @@
 import type { Readable, Writable } from "node:stream";
-import type { HeedFile, InstallChoices } from "./heed-file.js";
+import type { DataMode, HeedFile, InstallChoices } from "./heed-file.js";
 import type { PlannedAction } from "./plan.js";
 import { type AppliedResult } from "./render.js";
 /** Where the questions are read and drawn: the process's terminal unless a test injects streams. */
@@ -27,7 +27,9 @@ export declare function brandIntro(server: string, org: string | undefined, stre
 /** The person's choices, or null when they cancelled (Ctrl-C) at any question. */
 export declare function askChoices(agents: AgentOption[], current: HeedFile, streams: PromptStreams): Promise<InstallChoices | null>;
 /** Shows what the install will do and asks to go ahead; false when the person declines or cancels. */
-export declare function confirmInstall(agents: AgentLine[], streams: PromptStreams): Promise<boolean>;
+export declare function confirmInstall(agents: AgentLine[], details: string[], streams: PromptStreams): Promise<boolean>;
+/** The summary's lines about the whole install: what leaves the machine, and where the MCP connection points. */
+export declare function installDetails(heedFile: HeedFile, connector: string | undefined): string[];
 /** Runs the install behind a spinner; the spinner ends with the outcome either way. */
 export declare function installWithSpinner<T>(agentCount: number, work: () => Promise<T>, streams: PromptStreams): Promise<T>;
 /** One line per agent: a green tick and what it got, or what failed and why. */
@@ -45,3 +47,8 @@ export declare function agentLines(actions: PlannedAction[], names: ReadonlyMap<
 export declare function installCancelled(streams: PromptStreams): number;
 /** The closing lines after an install. */
 export declare function installFinished(lines: string[], streams: PromptStreams): void;
+/** What each data mode lets leave this machine, as the installer says it. */
+export declare const DATA_MODE_LABEL: Record<DataMode, {
+    label: string;
+    hint: string;
+}>;

package/dist/installer.js

@@ -4,9 +4,10 @@
  * the answers become `InstallChoices`, which cli.ts writes into heed.yaml and applies through the same
  * plan as every other install, so a second run starts from the last answers.
  */
-import { cancel, confirm, intro, isCancel, log, multiselect, note, outro, spinner } from "@clack/prompts";
+import { cancel, confirm, intro, isCancel, log, multiselect, note, outro, select, spinner } from "@clack/prompts";
 import { styleText } from "node:util";
 import { appliedFailed } from "./render.js";
+import { MCP_NEEDS_ORG } from "./mcp.js";
 const INTEGRATION_LABEL = { hooks: "hooks", mcp: "MCP server", skill: "skill", skip: "" };
 /** The header: the name, what Heedvane does, and which server and organization this install connects to. */
 export function brandIntro(server, org, streams) {
@@ -19,6 +20,9 @@ export async function askChoices(agents, current, streams) {
     const picked = await pickAgents(agents, current, streams);
     if (picked === null)
         return null;
+    const dataMode = await pickDataMode(current.heedvane.dataMode, streams);
+    if (dataMode === null)
+        return null;
     const install = await pickIntegrations(current.install, streams);
     if (install === null)
         return null;
@@ -28,18 +32,26 @@ export async function askChoices(agents, current, streams) {
     return {
         agents: sameAsDetected(picked, agents) ? "auto" : picked,
         install,
+        dataMode,
         steering: features.includes("steering"),
         skillChecks: features.includes("skillChecks"),
         memory: features.includes("memory"),
     };
 }
 /** Shows what the install will do and asks to go ahead; false when the person declines or cancels. */
-export async function confirmInstall(agents, streams) {
+export async function confirmInstall(agents, details, streams) {
     const footer = styleText("dim", "Choices are saved in ~/.heed/heed.yaml. Each config file is backed up before it changes.");
-    note([...agentRows(agents), "", footer].join("\n"), "Ready to install", streams);
+    note([...agentRows(agents), "", ...details, footer].join("\n"), "Ready to install", streams);
     const answer = await confirm({ message: "Install now?", initialValue: true, ...streams });
     return !isCancel(answer) && answer;
 }
+/** The summary's lines about the whole install: what leaves the machine, and where the MCP connection points. */
+export function installDetails(heedFile, connector) {
+    const lines = [`What leaves this machine: ${DATA_MODE_LABEL[heedFile.heedvane.dataMode].label}`];
+    if (!heedFile.install.mcp)
+        return lines;
+    return [...lines, connector === undefined ? MCP_NEEDS_ORG : `Heedvane's MCP connection: ${connector}`];
+}
 /** Runs the install behind a spinner; the spinner ends with the outcome either way. */
 export async function installWithSpinner(agentCount, work, streams) {
     const progress = spinner({ output: streams.output });
@@ -118,12 +130,26 @@ async function pickAgents(agents, current, streams) {
     });
     return isCancel(answer) ? null : answer;
 }
+/** What each data mode lets leave this machine, as the installer says it. */
+export const DATA_MODE_LABEL = {
+    "look-but-dont-keep": { label: "Look but don't keep", hint: "Heedvane's checks read prompts and tool calls, then keep only the verdict" },
+    "metrics-only": { label: "Metrics only", hint: "only counts and names leave; your organization's fixed rules still run here" },
+};
+async function pickDataMode(current, streams) {
+    const answer = await select({
+        message: "How much should leave this machine?",
+        options: Object.keys(DATA_MODE_LABEL).map((mode) => ({ value: mode, ...DATA_MODE_LABEL[mode] })),
+        initialValue: current,
+        ...streams,
+    });
+    return isCancel(answer) ? null : answer;
+}
 async function pickIntegrations(install, streams) {
     const answer = await multiselect({
         message: "What should Heedvane add to each agent?",
         options: [
             { value: "hooks", label: "Hooks", hint: "guardrails, skill checks and memory in every session" },
-            { value: "mcp", label: "MCP server", hint: "Heedvane's tools inside the agent" },
+            { value: "mcp", label: "MCP server", hint: "findings, reports and Heedvane's tools inside the agent" },
             { value: "skill", label: "Skill", hint: "teaches the agent how to use Heedvane" },
         ],
         initialValues: ["hooks", "mcp", "skill"].filter((kind) => install[kind]),

package/dist/listener/serve.js

@@ -103,7 +103,7 @@ export async function serveHooks(home, out) {
             let teamMemory;
             if (envelope.event === "session_start") {
                 // The one wait on Heedvane in a hook: the policy and the team memory's map, fetched together.
-                [, teamMemory] = await Promise.all([syncPolicySafely(), teamMemoryAtStart(org, envelope)]);
+                [, teamMemory] = await Promise.all([syncPolicySafely(), config.dataMode === "metrics-only" ? undefined : teamMemoryAtStart(org, envelope)]);
                 if (policy !== null)
                     sessionPolicies.set(envelope.session, policy);
             }

package/dist/listener/server.d.ts

@@ -39,6 +39,8 @@ export interface StartedListener {
  * length-leaking early return would defeat the point).
  */
 export declare function safeTokenEqual(a: string, b: string): boolean;
+/** `POST /shutdown` with the token: uninstall stops the listener it no longer has hooks for. */
+export declare const SHUTDOWN_ROUTE = "/shutdown";
 /**
  * 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

package/dist/listener/server.js

@@ -71,6 +71,20 @@ function sendJson(res, status, body) {
     res.end(JSON.stringify(body));
 }
 const ROUTE_PATTERN = /^\/hook\/([A-Za-z0-9_-]+)$/;
+/** `POST /shutdown` with the token: uninstall stops the listener it no longer has hooks for. */
+export const SHUTDOWN_ROUTE = "/shutdown";
+/** True after answering a token-carrying `POST /shutdown`; the listener closes once the answer is sent. */
+function handledShutdown(req, res, deps) {
+    if (req.method !== "POST" || new URL(req.url ?? "/", "http://127.0.0.1").pathname !== SHUTDOWN_ROUTE)
+        return false;
+    if (!hasValidToken(req, deps.token)) {
+        sendJson(res, 401, { error: "invalid or missing x-heed-agent-hook-token" });
+        return true;
+    }
+    res.on("finish", deps.stop);
+    sendJson(res, 200, { stopping: true });
+    return true;
+}
 /** 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);
@@ -150,6 +164,8 @@ function internalErrorResponder(res) {
     };
 }
 async function handleRequest(req, res, deps) {
+    if (handledShutdown(req, res, deps))
+        return;
     const agent = routeAgent(req, res, deps.agents);
     if (agent === null)
         return;
@@ -194,16 +210,20 @@ export async function startListener(options) {
     }
     const log = options.log ?? ((message) => console.log(message));
     const agents = options.knownAgents ?? KNOWN_AGENTS;
+    const server = createServer((req, res) => {
+        handleRequest(req, res, deps).catch(internalErrorResponder(res));
+    });
     const deps = {
         agents,
         token: endpoint.token,
         onEvent: options.onEvent,
         log,
         warned: new Set(),
+        stop: () => {
+            server.close();
+            server.closeAllConnections();
+        },
     };
-    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;

package/dist/mcp.d.ts

@@ -1,57 +1,28 @@
 /**
- * MCP registration entry builder per client.
+ * Heedvane's MCP connection: the one MCP entry the installer registers, named `heedvane`, pointing at
+ * the organization's remote server (`<server>/api/mcp/<org>`), in the shapes the dashboard's setup writes
+ * (apps/web/src/lib/agent/mcp-setup.ts `HEEDVANE_MCP_SERVER_NAME`). The agent signs in to it in the
+ * browser on first use.
  *
- * 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`.
+ * Identity: uninstall and detection recognize an entry by its name and shape together, never by a name
+ * alone: today's connection, the local helper earlier versions registered (`npx -y heedvane mcp`, under any
+ * name) and the connection under its earlier name `heedvane-findings`. Connect replaces the earlier ones.
  */
-/** Reserved server entry name. Presence of this NAME alone marks the entry ours. */
+/** The entry's name in every agent's MCP config. */
 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"];
+/** What to do when no organization is known, so no MCP connection can be registered. */
+export declare const MCP_NEEDS_ORG = "Heedvane's MCP connection needs your organization: run the connect command from your dashboard's Settings (it has --org), or npx heedvane connect --org <id>";
 /** 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.
- */
+/** The connection's URL for an organization, as the dashboard builds it (`buildHeedvaneMcpUrl`). */
+export declare function connectorUrl(server: string, org: string): string;
+/** The connection entry for this agent, or undefined when the installer does not register it there. `nodeDir` (POSIX only) is the installing Node's folder, for an entry that runs a local bridge. */
+export declare function connectorEntry(clientId: string, url: string, nodeDir?: string): Record<string, unknown> | undefined;
+/** Is this today's connection entry? Its name and a Heedvane MCP URL both have to match. */
+export declare function isConnectorEntry(name: string, entry: unknown): boolean;
+/** Is this an entry an earlier version wrote: the local helper under any name, or the connection under its earlier name? */
+export declare function isLegacyEntry(name: string, entry: unknown): boolean;
+/** Is this server entry Heedvane's, today's or an earlier version's? Used by uninstall, detection and doctor. */
 export declare function isHeedvaneEntry(name: string, entry: unknown): boolean;
+/** Names of the entries `match` accepts in a parsed config's MCP containers, as `container::name`. */
+export declare function mcpEntryNames(doc: Record<string, unknown>, containerKeys: string[], match: (name: string, entry: unknown) => boolean): string[];

package/dist/mcp.js

@@ -1,83 +1,114 @@
 /**
- * MCP registration entry builder per client.
+ * Heedvane's MCP connection: the one MCP entry the installer registers, named `heedvane`, pointing at
+ * the organization's remote server (`<server>/api/mcp/<org>`), in the shapes the dashboard's setup writes
+ * (apps/web/src/lib/agent/mcp-setup.ts `HEEDVANE_MCP_SERVER_NAME`). The agent signs in to it in the
+ * browser on first use.
  *
- * 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`.
+ * Identity: uninstall and detection recognize an entry by its name and shape together, never by a name
+ * alone: today's connection, the local helper earlier versions registered (`npx -y heedvane mcp`, under any
+ * name) and the connection under its earlier name `heedvane-findings`. Connect replaces the earlier ones.
  */
-/** Reserved server entry name. Presence of this NAME alone marks the entry ours. */
+/** The entry's name in every agent's MCP config. */
 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"];
+/** What to do when no organization is known, so no MCP connection can be registered. */
+export const MCP_NEEDS_ORG = "Heedvane's MCP connection needs your organization: run the connect command from your dashboard's Settings (it has --org), or npx heedvane connect --org <id>";
+/** The connection's name before 0.3.0; connect and uninstall remove an entry under it. */
+const EARLIER_CONNECTOR_NAME = "heedvane-findings";
+/** Names development builds of the local helper ran under, matched in its command and arguments. */
+const IDENTITY_MARKERS = ["@heedvane/hooks", "heedvane-hooks"];
+/** The local helper's arguments (its command was always `npx`). */
+const HELPER_ARGS = "-y heedvane mcp";
 /** 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 connection's URL for an organization, as the dashboard builds it (`buildHeedvaneMcpUrl`). */
+export function connectorUrl(server, org) {
+    return `${server.replace(/\/+$/, "")}/api/mcp/${encodeURIComponent(org)}`;
 }
 /**
- * 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.
+ * The connection entry per agent, in each agent's documented remote-server (Streamable HTTP) shape. Claude Code
+ * and VS Code need `type: "http"` (a typeless entry is read as stdio and skipped); Codex (`codex mcp add --url`)
+ * and Cursor take `url` alone, as the dashboard's setup writes them. Each agent signs in in the browser itself.
  */
-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";
+const CONNECTOR_ENTRY = {
+    claude: (url) => ({ type: "http", url }),
+    vscode: (url) => ({ type: "http", url }),
+    codex: (url) => ({ url }),
+    cursor: (url) => ({ url }),
+    // Gemini CLI: `httpUrl` is Streamable HTTP (`url` is SSE); OAuth is discovered on the first 401 (`/mcp auth heedvane`).
+    gemini: (url) => ({ httpUrl: url }),
+    // Qwen Code (a Gemini CLI fork) runs the OAuth flow only for a server whose `oauth` is enabled; endpoints and client are discovered.
+    "qwen-code": (url) => ({ httpUrl: url, oauth: { enabled: true } }),
+    opencode: (url) => ({ type: "remote", url, enabled: true }),
+    warp: (url) => ({ url }),
+    // Kimi Code: a `url` without `transport` is Streamable HTTP (`/mcp-config login heedvane` signs in).
+    kimi: (url) => ({ url }),
+    droid: (url) => ({ type: "http", url }),
+    // Antigravity and Windsurf read only `serverUrl` for a remote server.
+    antigravity: (url) => ({ serverUrl: url }),
+    windsurf: (url) => ({ serverUrl: url }),
+    // Copilot CLI lists the tools it may call; `*` is every tool.
+    copilot_cli: (url) => ({ type: "http", url, tools: ["*"] }),
+    // Claude Desktop's config file runs only local (stdio) servers, so the mcp-remote bridge carries the connection and
+    // its browser sign-in. `@latest` keeps npx off an older cached copy (0.1.15 and earlier had CVE-2025-6514).
+    claude_desktop: (url, nodeDir) => bridgeEntry(["-y", "mcp-remote@latest", url], nodeDir),
+};
 /**
- * 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.
+ * A local server run by npx. With the installing Node's folder, npx is named by its absolute path and that folder
+ * leads the server's PATH: Claude Desktop opened from Finder starts servers with launchd's PATH, which holds no
+ * Node from nvm, and npx finds `node` through PATH.
  */
-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) {
+function bridgeEntry(args, nodeDir) {
+    if (nodeDir === undefined)
+        return { command: "npx", args };
+    return { command: `${nodeDir}/npx`, args, env: { PATH: [nodeDir, "/usr/bin", "/bin", "/usr/sbin", "/sbin"].join(":") } };
+}
+/** The fields agents name a remote server's URL with. */
+const URL_FIELDS = ["url", "httpUrl", "serverUrl"];
+/** The connection entry for this agent, or undefined when the installer does not register it there. `nodeDir` (POSIX only) is the installing Node's folder, for an entry that runs a local bridge. */
+export function connectorEntry(clientId, url, nodeDir) {
+    return CONNECTOR_ENTRY[clientId]?.(url, nodeDir);
+}
+/** Does this entry point at a Heedvane MCP URL, under any agent's name for the field or as a bridge's argument? */
+function hasConnectorUrl(entry) {
+    if (entry === null || typeof entry !== "object")
+        return false;
+    const e = entry;
+    const args = Array.isArray(e.args) ? e.args : [];
+    return [...URL_FIELDS.map((field) => e[field]), ...args].some((url) => typeof url === "string" && url.includes("/api/mcp/"));
+}
+/** Is this today's connection entry? Its name and a Heedvane MCP URL both have to match. */
+export function isConnectorEntry(name, entry) {
+    return name === HEEDVANE_SERVER_NAME && hasConnectorUrl(entry);
+}
+/** Is this an entry an earlier version wrote: the local helper under any name, or the connection under its earlier name? */
+export function isLegacyEntry(name, entry) {
+    return hasHelperCommand(entry) || (name === EARLIER_CONNECTOR_NAME && hasConnectorUrl(entry));
+}
+/** Is this server entry Heedvane's, today's or an earlier version's? Used by uninstall, detection and doctor. */
+export function isHeedvaneEntry(name, entry) {
+    return isConnectorEntry(name, entry) || isLegacyEntry(name, entry);
+}
+/** Names of the entries `match` accepts in a parsed config's MCP containers, as `container::name`. */
+export function mcpEntryNames(doc, containerKeys, match) {
+    const names = [];
+    for (const key of new Set(containerKeys)) {
+        const container = doc[key];
+        if (container === null || typeof container !== "object" || Array.isArray(container))
+            continue;
+        for (const [name, entry] of Object.entries(container)) {
+            if (match(name, entry))
+                names.push(`${key}::${name}`);
+        }
+    }
+    return names;
+}
+/** Does this entry's command/args run the local helper (today's package name or a development build's)? */
+function hasHelperCommand(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);
+    return haystack.includes(HELPER_ARGS) || IDENTITY_MARKERS.some((m) => haystack.includes(m));
 }