heedvane 0.3.3 → 0.3.4

package/README.md

@@ -1,7 +1,7 @@
 # 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
@@ -9,7 +9,7 @@ npx heedvane
 
 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 or newer.
+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:
 
@@ -38,8 +38,14 @@ Scripts choose with `--mode look-but-dont-keep` or `--mode metrics-only`. The ch
   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. After a restart the hooks start it again by
-  themselves, at most once a minute. Set `HEED_LISTENER_AUTOSTART=0` to turn that off.
+- 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.
 
@@ -49,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
 
@@ -73,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). */