heedvane 0.0.0-stage → 0.1.0

package/dist/heed-file.js

@@ -0,0 +1,295 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { isScalar, parse, parseDocument } from "yaml";
+import { errorMessage, isRecord } from "./guards.js";
+/** Error raised for any invalid heed.yaml. The message is user-facing: keep it precise. */
+class HeedFileError extends Error {
+    constructor(message) {
+        super(`invalid heed.yaml: ${message}`);
+        this.name = "HeedFileError";
+    }
+}
+const TOP_LEVEL_KEYS = [
+    "schemaVersion",
+    "root",
+    "listener",
+    "agents",
+    "install",
+    "gating",
+    "heedvane",
+];
+/**
+ * The commented control file written by `npx heedvane init`.
+ * Kept loadable: loadHeedFile(DEFAULT_HEED_YAML_TEMPLATE) yields every default.
+ */
+export const DEFAULT_HEED_YAML_TEMPLATE = `# ~/.heed/heed.yaml — Heedvane agent hooks control file (v1)
+schemaVersion: v1
+
+# Where managed scripts and spool live. Default below; one install per machine.
+root: ~/.heed
+
+# The hook listener (Orca's pattern): loopback HTTP, token-authed, per-agent routes.
+listener:
+  port: 0            # 0 = pick a free port at first start, persist to endpoint.env
+  spool: true        # spool to disk when listener is unreachable (5 MB cap, 7-day TTL)
+
+# Which agents to manage. \`auto\` = every detected agent on the machine.
+agents: auto        # or an explicit list: [claude, codex, warp]
+
+# Which integrations to install per agent where supported.
+install:
+  hooks: true       # native hook config injection (skipped where the agent has none)
+  skill: true       # heedvane-hooks skill bundle -> ~/.agents/skills/heedvane-hooks/
+  mcp: true         # heedvane MCP server registration (universal fallback, incl. Warp)
+
+# Session gating (Orca's env-gated dispatcher pattern).
+gating:
+  mode: always      # always = every session; pane = only sessions launched with HEED_SESSION env
+
+# The Heedvane backend (credentials: npx heedvane auth, stored in ~/.heed/credentials.json).
+heedvane:
+  url: https://app.heedvane.com
+  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:
+    enforce: true     # deny skills that are not on the organization's approved list
+    strict: false     # also require the local SKILL.md to match the approved revision
+    whenUnknown: allow  # no synced list (run npx heedvane skills sync) or listener down: allow or deny
+`;
+function describeType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    return typeof value;
+}
+function expectMapping(value, key) {
+    if (!isRecord(value)) {
+        throw new HeedFileError(`"${key}" must be a mapping, got ${describeType(value)}`);
+    }
+    return value;
+}
+function rejectUnknownKeys(value, allowed, where) {
+    const unknown = Object.keys(value).filter((k) => !allowed.includes(k));
+    if (unknown.length > 0) {
+        throw new HeedFileError(`"${where}" has unknown key(s): ${unknown.map((k) => JSON.stringify(k)).join(", ")} (allowed: ${allowed.join(", ")})`);
+    }
+}
+function expectBool(value, key) {
+    if (typeof value !== "boolean") {
+        throw new HeedFileError(`"${key}" must be a boolean, got ${describeType(value)}`);
+    }
+    return value;
+}
+function validateListener(raw) {
+    const defaults = { port: 0, spool: true };
+    if (raw === undefined)
+        return defaults;
+    const map = expectMapping(raw, "listener");
+    rejectUnknownKeys(map, ["port", "spool"], "listener");
+    const out = defaults;
+    if (map["port"] !== undefined) {
+        const port = map["port"];
+        if (typeof port !== "number" || !Number.isInteger(port) || port < 0) {
+            throw new HeedFileError(`"listener.port" must be an integer >= 0, got ${describeType(port)}`);
+        }
+        out.port = port;
+    }
+    if (map["spool"] !== undefined)
+        out.spool = expectBool(map["spool"], "listener.spool");
+    return out;
+}
+function validateAgents(raw) {
+    if (raw === undefined)
+        return "auto";
+    if (raw === "auto")
+        return "auto";
+    if (!Array.isArray(raw)) {
+        throw new HeedFileError(`"agents" must be "auto" or a list of agent ids, got ${describeType(raw)}`);
+    }
+    for (const entry of raw) {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new HeedFileError(`"agents" entries must be non-empty strings, got ${JSON.stringify(entry) ?? describeType(entry)}`);
+        }
+    }
+    return raw.map((entry) => entry.trim());
+}
+function validateInstall(raw) {
+    const defaults = { hooks: true, skill: true, mcp: true };
+    if (raw === undefined)
+        return defaults;
+    const map = expectMapping(raw, "install");
+    rejectUnknownKeys(map, ["hooks", "skill", "mcp"], "install");
+    const out = defaults;
+    if (map["hooks"] !== undefined)
+        out.hooks = expectBool(map["hooks"], "install.hooks");
+    if (map["skill"] !== undefined)
+        out.skill = expectBool(map["skill"], "install.skill");
+    if (map["mcp"] !== undefined)
+        out.mcp = expectBool(map["mcp"], "install.mcp");
+    return out;
+}
+function validateGating(raw) {
+    const defaults = { mode: "always" };
+    if (raw === undefined)
+        return defaults;
+    const map = expectMapping(raw, "gating");
+    rejectUnknownKeys(map, ["mode"], "gating");
+    const out = defaults;
+    if (map["mode"] !== undefined) {
+        const mode = map["mode"];
+        if (mode !== "pane" && mode !== "always") {
+            throw new HeedFileError(`"gating.mode" must be "pane" or "always", got ${JSON.stringify(mode)}`);
+        }
+        out.mode = mode;
+    }
+    return out;
+}
+function validateSkills(raw) {
+    const out = { enforce: true, strict: false, whenUnknown: "allow" };
+    if (raw === undefined)
+        return out;
+    const map = expectMapping(raw, "heedvane.skills");
+    rejectUnknownKeys(map, ["enforce", "strict", "whenUnknown"], "heedvane.skills");
+    if (map["enforce"] !== undefined)
+        out.enforce = expectBool(map["enforce"], "heedvane.skills.enforce");
+    if (map["strict"] !== undefined)
+        out.strict = expectBool(map["strict"], "heedvane.skills.strict");
+    const whenUnknown = map["whenUnknown"];
+    if (whenUnknown !== undefined) {
+        if (whenUnknown !== "allow" && whenUnknown !== "deny") {
+            throw new HeedFileError(`"heedvane.skills.whenUnknown" must be "allow" or "deny", got ${JSON.stringify(whenUnknown)}`);
+        }
+        out.whenUnknown = whenUnknown;
+    }
+    return out;
+}
+function validateHeedvane(raw) {
+    const out = { url: "https://app.heedvane.com", steering: true, memory: true, skills: validateSkills(undefined) };
+    if (raw === undefined)
+        return out;
+    const map = expectMapping(raw, "heedvane");
+    rejectUnknownKeys(map, ["url", "steering", "memory", "skills"], "heedvane");
+    const url = map["url"];
+    if (url !== undefined) {
+        if (typeof url !== "string" || !URL.canParse(url) || !/^https?:$/.test(new URL(url).protocol)) {
+            throw new HeedFileError(`"heedvane.url" must be an http(s) URL, got ${JSON.stringify(url)}`);
+        }
+        out.url = url.replace(/\/+$/, "");
+    }
+    if (map["steering"] !== undefined)
+        out.steering = expectBool(map["steering"], "heedvane.steering");
+    if (map["memory"] !== undefined)
+        out.memory = expectBool(map["memory"], "heedvane.memory");
+    out.skills = validateSkills(map["skills"]);
+    return out;
+}
+/**
+ * Parse and validate a heed.yaml document, returning the fully normalized file.
+ * Throws {@link HeedFileError} (message prefixed "invalid heed.yaml:") on any problem:
+ * unparseable YAML, non-mapping root, missing/unknown schemaVersion, unknown keys
+ * (top-level or nested), or wrong-typed values.
+ */
+export function loadHeedFile(text) {
+    let raw;
+    try {
+        raw = parse(text);
+    }
+    catch (err) {
+        const reason = errorMessage(err);
+        throw new HeedFileError(`could not parse YAML — ${reason}`);
+    }
+    if (!isRecord(raw)) {
+        throw new HeedFileError(`expected a top-level mapping, got ${describeType(raw)}`);
+    }
+    const schemaVersion = raw["schemaVersion"];
+    if (schemaVersion === undefined) {
+        throw new HeedFileError(`missing required key "schemaVersion" (expected "v1")`);
+    }
+    if (schemaVersion !== "v1") {
+        throw new HeedFileError(`unsupported schemaVersion ${JSON.stringify(schemaVersion)} — this CLI supports "v1" only (key: schemaVersion)`);
+    }
+    rejectUnknownKeys(raw, TOP_LEVEL_KEYS, "top level");
+    const root = raw["root"];
+    if (root !== undefined && (typeof root !== "string" || root.trim().length === 0)) {
+        throw new HeedFileError(`"root" must be a non-empty string, got ${describeType(root)}`);
+    }
+    return {
+        schemaVersion: "v1",
+        root: root === undefined ? "~/.heed" : root,
+        listener: validateListener(raw["listener"]),
+        agents: validateAgents(raw["agents"]),
+        install: validateInstall(raw["install"]),
+        gating: validateGating(raw["gating"]),
+        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) {
+    const document = parseDocument(text);
+    const current = document.getIn(["heedvane", "url"], true);
+    if (isScalar(current))
+        current.value = url;
+    else
+        document.setIn(["heedvane", "url"], url);
+    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"]];
+const toStderr = (line) => void process.stderr.write(`${line}\n`);
+/**
+ * Load the heed.yaml at `path`. A retired key an earlier version wrote (`init` put `steeringTimeoutMs`
+ * in every heed.yaml) is removed from the file in place, its value never read, and one line says so; if
+ * the file cannot be rewritten the key is ignored in memory and the line says that instead.
+ */
+export function loadHeedFileAt(path, log = toStderr) {
+    const text = readFileSync(path, "utf8");
+    const document = parseDocument(text);
+    const retired = document.errors.length > 0 ? [] : RETIRED_KEYS.filter((path) => document.hasIn(path));
+    if (retired.length === 0)
+        return loadHeedFile(text);
+    const names = retired.map((path) => path.join(".")).join(", ");
+    for (const path of retired)
+        document.deleteIn(path);
+    const refusal = rewriteInPlace(path, document);
+    if (refusal === null) {
+        log(`[heedvane] removed ${names} from ${path}: no hook waits on Heedvane any more`);
+        return loadHeedFile(String(document));
+    }
+    // The file stays as it was (an alias to the removed key cannot be written back, or the disk refused): load it without the key.
+    log(`[heedvane] could not remove ${names} from ${path} (${errorMessage(refusal)}); it is ignored`);
+    return loadHeedFile(JSON.stringify(withoutKeys(parse(text), retired)));
+}
+/** Writes the document over `path`; the error that stopped it, or null. */
+function rewriteInPlace(path, document) {
+    try {
+        writeFileAtomic.sync(path, String(document), { mode: 0o600 });
+        return null;
+    }
+    catch (err) {
+        return err ?? new Error("write refused");
+    }
+}
+/** A parsed heed.yaml less the retired keys. */
+function withoutKeys(value, retired) {
+    if (!isRecord(value))
+        return value;
+    const kept = Object.fromEntries(Object.entries(value).filter(([key]) => !retired.some((path) => path.length === 1 && path[0] === key)));
+    const heedvane = kept["heedvane"];
+    if (!isRecord(heedvane))
+        return kept;
+    const nested = retired.filter((path) => path.length === 2 && path[0] === "heedvane").map((path) => path[1]);
+    return { ...kept, heedvane: Object.fromEntries(Object.entries(heedvane).filter(([key]) => !nested.includes(key))) };
+}
+/** heed.yaml's `heedvane` section under `root`; the template's defaults before init has written one. */
+export function heedvaneConfigAt(root) {
+    try {
+        return loadHeedFileAt(join(root, "heed.yaml")).heedvane;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        return loadHeedFile(DEFAULT_HEED_YAML_TEMPLATE).heedvane;
+    }
+}

package/dist/listener/endpoint.d.ts

@@ -0,0 +1,21 @@
+/** The listener's loopback endpoint, persisted under the heed root. */
+export interface Endpoint {
+    port: number;
+    token: string;
+}
+/** Path of the endpoint file: `root/endpoint.env`. */
+export declare function endpointPath(root: string): string;
+/**
+ * Read `{port, token}` from `root/endpoint.env`.
+ * Returns null when the file does not exist. If the file exists but is
+ * missing/incoherent, the corresponding field degrades (`port` -> 0,
+ * `token` -> "") so callers can produce a precise remediation error.
+ */
+export declare function readEndpoint(root: string): Promise<Endpoint | null>;
+/** Atomically write `root/endpoint.env` (mode 0600) with the port and token lines. */
+export declare function writeEndpoint(root: string, endpoint: Endpoint): Promise<void>;
+/**
+ * The listener endpoint, issued once: an existing endpoint.env with a port and token is kept
+ * (dispatchers already point at it); otherwise a free loopback port and a fresh 256-bit token are written.
+ */
+export declare function ensureEndpoint(root: string): Promise<Endpoint>;

package/dist/listener/endpoint.js

@@ -0,0 +1,112 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, open, readFile, rename } from "node:fs/promises";
+import { createServer } from "node:net";
+import { basename, dirname, join } from "node:path";
+import { unlinkOptional } from "../best-effort.js";
+/** The variable names the dispatcher scripts and the Hermes plugin read, sourced straight from endpoint.env. */
+const PORT_KEY = "HEED_AGENT_HOOK_PORT";
+const TOKEN_KEY = "HEED_AGENT_HOOK_TOKEN";
+/** Path of the endpoint file: `root/endpoint.env`. */
+export function endpointPath(root) {
+    return join(root, "endpoint.env");
+}
+/** Parse KEY=VALUE lines (ignores blanks, `#` comments, and matching quotes). */
+function parseEnvFile(content) {
+    const values = {};
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1).trim();
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        values[key] = value;
+    }
+    return values;
+}
+/**
+ * Read `{port, token}` from `root/endpoint.env`.
+ * Returns null when the file does not exist. If the file exists but is
+ * missing/incoherent, the corresponding field degrades (`port` -> 0,
+ * `token` -> "") so callers can produce a precise remediation error.
+ */
+export async function readEndpoint(root) {
+    let content;
+    try {
+        content = await readFile(endpointPath(root), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const values = parseEnvFile(content);
+    const port = Number.parseInt(values[PORT_KEY] ?? "", 10);
+    return {
+        port: Number.isInteger(port) && port >= 0 && port <= 65535 ? port : 0,
+        token: values[TOKEN_KEY] ?? "",
+    };
+}
+/**
+ * Atomic write: temp file in the same directory (created 0600, fsync'd,
+ * chmod'd to defeat umask), then rename over the target. Same contract as
+ * write-file-atomic, kept stdlib-only so the listener has zero deps.
+ */
+async function atomicWriteFile(filePath, data, mode) {
+    const dir = dirname(filePath);
+    await mkdir(dir, { recursive: true });
+    const tmp = join(dir, `.${basename(filePath)}.${process.pid}.${Date.now().toString(36)}.tmp`);
+    const handle = await open(tmp, "w", mode);
+    try {
+        await handle.writeFile(data, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await chmod(tmp, mode);
+        await rename(tmp, filePath);
+    }
+    catch (err) {
+        await unlinkOptional(tmp);
+        throw err;
+    }
+}
+/** Atomically write `root/endpoint.env` (mode 0600) with the port and token lines. */
+export async function writeEndpoint(root, endpoint) {
+    const content = `${PORT_KEY}=${endpoint.port}\n${TOKEN_KEY}=${endpoint.token}\n`;
+    await atomicWriteFile(endpointPath(root), content, 0o600);
+}
+/** A loopback port free right now (the OS picks it). */
+async function freeLoopbackPort() {
+    const server = createServer();
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    await new Promise((resolve) => server.close(() => resolve()));
+    if (address === null || typeof address !== "object")
+        throw new Error("could not reserve a loopback port");
+    return address.port;
+}
+/**
+ * The listener endpoint, issued once: an existing endpoint.env with a port and token is kept
+ * (dispatchers already point at it); otherwise a free loopback port and a fresh 256-bit token are written.
+ */
+export async function ensureEndpoint(root) {
+    const existing = await readEndpoint(root);
+    if (existing !== null && existing.port > 0 && existing.token)
+        return existing;
+    const endpoint = { port: await freeLoopbackPort(), token: randomBytes(32).toString("hex") };
+    await writeEndpoint(root, endpoint);
+    return endpoint;
+}

package/dist/listener/forward.d.ts

@@ -0,0 +1,36 @@
+import { type Backend } from "../backend/client.js";
+/** Held while Heedvane is unreachable; past this, the oldest {@link SHED_FRACTION} moves to the dead-letter file in one rewrite. */
+export declare const QUEUE_MAX = 5000;
+/** Held while the route refuses this machine outright (403) or does not exist (404): nothing will change soon. */
+export declare const REFUSED_QUEUE_MAX = 500;
+/** The dead-letter file turns over at this size (the old one is kept once as `.1`), so a permanent refusal cannot fill the disk. */
+export declare const DEAD_LETTER_MAX_BYTES: number;
+/** How often an item refused on its own is retried before it is dead-lettered. */
+export declare const MAX_REFUSALS = 3;
+export interface Outbox<T> {
+    /** Queue an item; it is on disk when this resolves. It is stamped with the current sign-in, or with `identity` when the caller read it earlier (a replayed event belongs to the sign-in the replay began under). */
+    add: (item: T, identity?: string | null) => Promise<void>;
+    /** Send everything queued; what could not be sent stays queued for the next flush. One at a time. */
+    flush: () => Promise<void>;
+}
+export interface OutboxRoute {
+    /** The outbox's file name stem under `<root>/spool`. */
+    name: string;
+    path: string;
+    /** The body's array key, `{ [key]: items }`, also the first element of a 400's issue paths. */
+    key: string;
+    maxItems: number;
+    maxBytes: number;
+}
+/** Steering's delivery reports: at most 100 per post and 256 KiB per body (a little headroom for the wrapper). */
+export declare const DELIVERIES_ROUTE: OutboxRoute;
+export interface OutboxContext {
+    /** The heed root; the outbox lives in its spool directory. */
+    root: string;
+    backend: Backend | null;
+    log: (message: string) => void;
+    /** The clock the backoff reads (tests move it). */
+    now?: () => number;
+}
+/** An outbox for one route, loaded with whatever an earlier listener left unsent. Without a backend it only queues. */
+export declare function outbox<T>(route: OutboxRoute, { root, backend, log, now }: OutboxContext): Promise<Outbox<T>>;