heedvane 0.2.1 → 0.3.4

package/README.md

@@ -1,15 +1,15 @@
 # heedvane
 
 Connect the coding agents on your machine to your Heedvane organization: guardrails, approved-skill
-checks and team memory for Claude Code, Codex, Cursor, Gemini CLI, Hermes, OpenCode and more.
+checks and team memory for Claude Code, Codex, Cursor, Gemini CLI, Hermes, OpenCode, Pi and more.
 
 ```sh
 npx heedvane
 ```
 
-The installer shows the agents it found on your machine. Tick the ones you want, choose what Heedvane
-adds and does, confirm. It installs, starts Heedvane in the background and signs you in through the
-browser. It needs Node.js 22 or newer.
+The installer shows the agents it found on your machine. Tick the ones you want, choose how much leaves
+your machine, choose what Heedvane adds and does, confirm. It installs, starts Heedvane in the background and signs you in through the
+browser. It needs Node.js 22.5 or newer.
 
 Your dashboard's Agents page has the same command with your server and organization filled in:
 
@@ -17,14 +17,35 @@ Your dashboard's Agents page has the same command with your server and organizat
 npx heedvane connect --server https://app.heedvane.com --org <organization id>
 ```
 
+## How much leaves your machine
+
+| Choice | What leaves your machine |
+| --- | --- |
+| **Look but don't keep** (default) | Heedvane's guardrail checks read the prompt or tool call, then keep only the verdict, never the text. |
+| **Metrics only** | Only counts and names. Your organization's fixed rules still run on your machine; Heedvane's own checks and team memory are off. |
+
+Scripts choose with `--mode look-but-dont-keep` or `--mode metrics-only`. The choice is saved in
+`heed.yaml` as `heedvane.dataMode`.
+
 ## What it changes
 
 - Writes `~/.heed/heed.yaml`, your control file, with your answers. Run `npx heedvane` again to change
   them.
-- Adds Heedvane's hooks, MCP server entry and skill to each agent you ticked. A config file it edits is
-  backed up first.
-- Starts Heedvane's local listener, which answers the hooks. After a restart the hooks start it again by
-  themselves, at most once a minute. Set `HEED_LISTENER_AUTOSTART=0` to turn that off.
+- Adds Heedvane's hooks and skill to each agent you ticked. A config file it edits is backed up first.
+- With `--org` (the dashboard's command has it), also adds Heedvane's MCP connection, named `heedvane`, for
+  your organization (findings, reports and agent feedback) in every agent you ticked. Claude Desktop gets it
+  through the `mcp-remote` bridge, run with the Node.js that installed it (run `npx heedvane connect` again after
+  removing that Node version). The agent signs in
+  through the browser the first time it uses it. It replaces the `heedvane` and
+  `heedvane-findings` entries an earlier version added.
+- Starts Heedvane's local listener, which answers the hooks. Every command makes sure it runs your current settings
+  and sign-in: it replaces one from an older version and keeps a newer one. After you edit `heed.yaml` by hand, run
+  `npx heedvane listener restart`. After a reboot the hooks start it again by themselves, at most once a minute (on
+  Windows they run in Git Bash, from Git for Windows). Set `HEED_LISTENER_AUTOSTART=0` to turn that off. While the listener cannot answer, Claude Code,
+  Codex, Gemini CLI and Pi tell you once per session that actions are not being checked. The listener trusts its
+  machine: run your agents under one OS user per machine, and give each user on a shared server its own container or VM.
+  If you pin `HEED_AGENT_HOOK_PORT` and `HEED_AGENT_HOOK_TOKEN` in an agent's environment, pin `HEED_AGENT_HOOK_PROOF`
+  from `~/.heed/endpoint.env` too; without it every hook runs Node and waits a quarter second before it is answered.
 
 Run `npx heedvane connect --dry-run` to see every file it would touch without writing anything.
 
@@ -34,22 +55,47 @@ Agents that run unattended (a factory looping on a server, a CI job, a container
 package without the installer:
 
 ```sh
-# Once, when you build the image: install the hooks for the agent the factory runs
+# Install the hooks and Heedvane's MCP connection (also fine while the image is built)
 npx -y heedvane connect --server https://app.heedvane.com --org <organization id> --agent claude --yes
 
-# When the container starts: sign in with an organization key from your secret store
-printf '%s' "$HEEDVANE_ORG_KEY" | npx heedvane auth org
+# Where the agent runs, with HEEDVANE_ORG_KEY set from your secret store: sign in with the key.
+# This also switches Heedvane's MCP connection to sending that key.
+printf '%s' "$HEEDVANE_ORG_KEY" | npx -y heedvane auth org
 
 # Every agent run: Heedvane answers the hooks for exactly this run
-npx heedvane run -- claude -p "fix the failing tests"
+npx -y heedvane run -- claude -p "fix the failing tests"
 ```
 
+Once an organization key is saved with `auth org` (or `HEEDVANE_ORG_KEY` is set), Heedvane's MCP connection
+(named `heedvane`) sends the key from `HEEDVANE_ORG_KEY` as `Authorization: Bearer`, through the agent's own way
+to read an environment variable: the key is never written to a config file, and no browser sign-in is needed.
+The commands work in either order: `auth org` switches a connection that `connect` installed earlier. Keep
+`HEEDVANE_ORG_KEY` set while the agent runs, because the agent reads it when it starts; `doctor` says when it is
+not set. Claude Code, Codex, Cursor, Gemini CLI, Qwen Code, OpenCode, Droid, Kimi Code, Copilot CLI, Windsurf and Pi
+support this; VS Code, Warp, Antigravity and Claude Desktop keep the browser sign-in.
+
 `run` keeps the agent's terminal output and exit code, so your pipeline reads them as before. Heedvane's
 own lines go to stderr and `~/.heed/listener.log`.
 
 - Claude Code runs the hooks in print mode (`claude -p`), but not with `--bare`.
 - Codex runs hooks only after they are trusted.
-- The installer does not set up Pi or Flue. Connect them with a hook of your own that sends each action to `POST /api/agent/steering` with the organization key; Heedvane answers whether to refuse it.
+- Pi runs Heedvane's guard as an extension: `npx -y heedvane run -- pi -p "<your task>"`.
+
+## Agents you build on Pi
+
+Code built on Pi's core (`@earendil-works/pi-agent-core`) or on Pi Durable (`@earendil-works/pi-durable`) asks
+Heedvane before each tool runs with the guard this package exports. Install `heedvane` beside your agent and add
+one line:
+
+```ts
+import { beforeToolCall, beforeTool } from "heedvane/guard";
+
+new Agent({ ...options, beforeToolCall }); // Pi's core
+registry.install(defineExtension({ name: "heedvane", hooks: [hook(ToolTask, { beforeTool })] })); // Pi Durable
+```
+
+Run the agent with `npx -y heedvane run -- <command>`, or on a machine where Heedvane's listener runs. When the listener cannot
+answer, the guard lets the tool run, keeps the call for the listener and starts one, as the agents' hooks do.
 
 ## Everyday commands
 
@@ -58,6 +104,7 @@ own lines go to stderr and `~/.heed/listener.log`.
 | `npx heedvane` | Opens the installer: change agents and features any time. |
 | `npx heedvane doctor` | Checks the install and prints a fix for each problem. |
 | `npx heedvane listener start` | Runs the listener in the foreground. |
+| `npx heedvane listener restart` | Makes sure the background listener runs your current settings, after a hand edit of `heed.yaml`. |
 | `npx heedvane run -- <command>` | Runs one agent with Heedvane, for CI and containers. |
 | `npx heedvane uninstall` | Removes only the entries Heedvane added. `heed.yaml` stays. |
 | `npx heedvane --help` | Lists every command and flag. |

package/dist/backend/credentials.d.ts

@@ -3,6 +3,8 @@ import { type LoginTokenOptions } from "./login.js";
 export type CredentialKind = "org";
 export type Credentials = Partial<Record<CredentialKind, string>>;
 export declare function credentialsPath(root: string): string;
+/** True when this machine signs in with a saved organization key: a software factory (`auth org`), with no login, which would win. */
+export declare function signsInWithOrgKey(root: string): boolean;
 /** Store one key beside the others, 0600. */
 export declare function saveCredential(root: string, kind: CredentialKind, key: string): Promise<void>;
 /** Heedvane at `url` when this machine has a sign-in or a key now, else null. The credential is read again on every call. */

package/dist/backend/credentials.js

@@ -4,6 +4,7 @@
  * `npx heedvane auth org` in `<root>/credentials.json`, mode 0600, kept apart from heed.yaml (a file
  * people share). A machine uses one of them: the login when there is one, else the key.
  */
+import { existsSync, readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
@@ -33,6 +34,18 @@ async function readCredentials(root) {
     }
     return out;
 }
+/** True when this machine signs in with a saved organization key: a software factory (`auth org`), with no login, which would win. */
+export function signsInWithOrgKey(root) {
+    if (existsSync(join(root, "login.json")))
+        return false;
+    try {
+        const value = JSON.parse(readFileSync(credentialsPath(root), "utf8"));
+        return isRecord(value) && typeof value["org"] === "string" && value["org"] !== "";
+    }
+    catch {
+        return false; // no key saved, or a file that does not parse: no key to send
+    }
+}
 /** Store one key beside the others, 0600. */
 export async function saveCredential(root, kind, key) {
     const next = { ...(await readCredentials(root)), [kind]: key };

package/dist/backend/repo-remote.js

@@ -55,7 +55,8 @@ export function withoutCredentials(remote) {
 export function repositoryName(remote) {
     const trimmed = remote.trim();
     const colon = trimmed.indexOf(":");
-    const url = URL.parse(trimmed.includes("://") || colon <= 0 ? trimmed : `ssh://${trimmed.slice(0, colon)}/${trimmed.slice(colon + 1)}`);
+    const origin = trimmed.includes("://") || colon <= 0 ? trimmed : `ssh://${trimmed.slice(0, colon)}/${trimmed.slice(colon + 1)}`;
+    const url = URL.canParse(origin) ? new URL(origin) : null; // not URL.parse: Node 22.0 has none
     const path = url?.pathname.replace(/\/+$/, "").replace(/\.git$/i, "").replace(/^\/+/, "") ?? "";
     return path.includes("/") ? path : "";
 }

package/dist/backend/sign-in-change.js

@@ -22,6 +22,7 @@ import { mkdir, readdir, readFile, rename, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { signInIdentity } from "./credentials.js";
+import { OTHER_SIGN_IN_DIR } from "../hook-fallback.js";
 import { isPaneSpoolFile, spoolDir } from "../listener/spool.js";
 import { steeringPolicyPath } from "../steering/rules.js";
 /** The file that records whose sign-in the spool, instructions and caches on this machine belong to. */
@@ -58,9 +59,9 @@ async function setAsideSignInLeftovers(root) {
     const spool = spoolDir(root);
     const names = (await readdir(spool).catch(() => [])).filter(isPaneSpoolFile);
     if (names.length > 0)
-        await mkdir(join(spool, "other-sign-in"), { recursive: true, mode: 0o700 });
+        await mkdir(join(spool, OTHER_SIGN_IN_DIR), { recursive: true, mode: 0o700 });
     for (const name of names)
-        await rename(join(spool, name), join(spool, "other-sign-in", `${Date.now()}-${name}`));
+        await rename(join(spool, name), join(spool, OTHER_SIGN_IN_DIR, `${Date.now()}-${name}`));
     await discardSteeringCaches(root);
 }
 /** The pre-rendered instructions and the cached policy of an earlier sign-in; the next sync writes the current one's. */

package/dist/cli.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { type ListenerOutcome } from "./listener/background.js";
 import { type PromptStreams } from "./installer.js";
 export interface MainOptions {
     /** Env override (tests inject HEED_HOME fixtures). Defaults to process.env. */
@@ -16,7 +17,7 @@ export interface MainOptions {
     /** Where the interactive installer reads keys and draws; defaults to the terminal (tests inject streams). */
     prompts?: PromptStreams;
     /** Starts the listener in the background for the installer; defaults to a detached `listener start` (tests pass a stand-in). */
-    startListener?: (home: string) => Promise<boolean>;
+    ensureListener?: (home: string) => Promise<ListenerOutcome>;
 }
 declare function main(argv: string[], opts?: MainOptions): Promise<number>;
 /** All of stdin as text (where `auth` reads its key). */
@@ -25,5 +26,6 @@ declare function main(argv: string[], opts?: MainOptions): Promise<number>;
  * The command that opens `url` in the default browser. Windows goes through rundll32, not `cmd /c start`:
  * cmd would cut the sign-in URL at its first `&`.
  */
-export declare function browserOpener(platform: NodeJS.Platform, url: string): [string, string[]];
+/** The command that opens `url`: `$BROWSER` when set (a no-op such as `true` keeps captures and tests off a real browser), else the platform's opener. */
+export declare function browserOpener(platform: NodeJS.Platform, url: string, browser?: string): [string, string[]];
 export { main };