heedvane 0.0.0-stage → 0.1.0

package/dist/events/contract.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Canonical event contract (v1) — the harness-neutral layer everything else talks to.
+ *
+ * Events are snake_case; the envelope is the single shape the listener emits and
+ * the spool carries. Field caps (8 KB strings, 500 nodes, depth 5) are Orca's
+ * numbers: ingest must never be blown up by a hostile payload.
+ */
+export declare const CANONICAL_EVENTS: readonly ["session_start", "session_end", "user_prompt_submit", "pre_tool_use", "post_tool_use", "post_tool_use_failure", "permission_request", "stop", "stop_failure", "subagent_start", "subagent_stop", "notification", "pre_compact"];
+export type CanonicalEvent = (typeof CANONICAL_EVENTS)[number];
+/** Events that no harness maps to land here as `unknown_event` (data preserved in payload). */
+export declare const UNKNOWN_EVENT = "unknown_event";
+export declare const MAX_STRING_LENGTH = 8192;
+export declare const MAX_OBJECT_NODES = 500;
+export declare const TRUNCATION_SUFFIX = "...[truncated]";
+export interface Envelope {
+    v: 1;
+    event: string;
+    agent: string;
+    session: string;
+    pane: string;
+    receivedAt: string;
+    payload: Record<string, unknown>;
+    /**
+     * Unique per event: generated by the dispatcher (`X-Heed-Event-Id`), kept through spool and replay,
+     * so Heedvane can drop a duplicate. Set by the listener; `normalize` alone leaves it out.
+     */
+    id?: string;
+    /** The checkout's `git remote get-url origin`, credentials stripped; set when forwarding to ingestion. */
+    gitOrigin?: string;
+    /** The session's checkout top level (`git rev-parse --show-toplevel`, absolute); set when forwarding, absent outside a checkout. */
+    repoRoot?: string;
+    /**
+     * SHA-256 hex of the exact bytes of the SKILL.md a tool event loaded, set when forwarding, so
+     * statistics can tell an approved copy from a modified one. Absent when the file cannot be read.
+     */
+    skillSha256?: string;
+}
+export interface CapBudget {
+    nodes: number;
+}
+export declare function isCanonicalEvent(name: string): name is CanonicalEvent;
+/**
+ * Truncate a string to MAX_STRING_LENGTH, appending '...[truncated]' when cut. The cut never splits a
+ * surrogate pair, NUL characters are removed and lone surrogates become U+FFFD: Postgres jsonb refuses
+ * `\u0000` and unpaired surrogates, and ingestion would refuse the whole batch for one of them.
+ */
+export declare function capString(value: string): string;
+/**
+ * Cap a value for ingest: strings to 8 KB, the whole value to 500 nodes, nesting
+ * to depth 5 (depth 0 = the top-level value). Over-budget subtrees are replaced
+ * with '...[truncated]'. Pass a shared {@link CapBudget} to count nodes across
+ * several top-level fields of the same payload.
+ */
+export declare function capValue(value: unknown, budget?: CapBudget, depth?: number): unknown;

package/dist/events/contract.js

@@ -0,0 +1,87 @@
+import { isRecord } from "../guards.js";
+/**
+ * Canonical event contract (v1) — the harness-neutral layer everything else talks to.
+ *
+ * Events are snake_case; the envelope is the single shape the listener emits and
+ * the spool carries. Field caps (8 KB strings, 500 nodes, depth 5) are Orca's
+ * numbers: ingest must never be blown up by a hostile payload.
+ */
+export const CANONICAL_EVENTS = [
+    "session_start",
+    "session_end",
+    "user_prompt_submit",
+    "pre_tool_use",
+    "post_tool_use",
+    "post_tool_use_failure",
+    "permission_request",
+    "stop",
+    "stop_failure",
+    "subagent_start",
+    "subagent_stop",
+    "notification",
+    "pre_compact",
+];
+/** Events that no harness maps to land here as `unknown_event` (data preserved in payload). */
+export const UNKNOWN_EVENT = "unknown_event";
+export const MAX_STRING_LENGTH = 8192;
+export const MAX_OBJECT_NODES = 500;
+const MAX_OBJECT_DEPTH = 5;
+export const TRUNCATION_SUFFIX = "...[truncated]";
+export function isCanonicalEvent(name) {
+    return CANONICAL_EVENTS.includes(name);
+}
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+/**
+ * Truncate a string to MAX_STRING_LENGTH, appending '...[truncated]' when cut. The cut never splits a
+ * surrogate pair, NUL characters are removed and lone surrogates become U+FFFD: Postgres jsonb refuses
+ * `\u0000` and unpaired surrogates, and ingestion would refuse the whole batch for one of them.
+ */
+export function capString(value) {
+    const clean = value.replaceAll("\0", "").replace(LONE_SURROGATE, "\uFFFD");
+    if (clean.length <= MAX_STRING_LENGTH)
+        return clean;
+    const end = /[\uD800-\uDBFF]/.test(clean[MAX_STRING_LENGTH - 1]) ? MAX_STRING_LENGTH - 1 : MAX_STRING_LENGTH;
+    return clean.slice(0, end) + TRUNCATION_SUFFIX;
+}
+/** The scalar / fallback arm of capValue: everything that is not an array or record. */
+function capScalar(value) {
+    if (value === null || typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (typeof value === "bigint")
+        return capString(value.toString());
+    if (typeof value === "string")
+        return capString(value);
+    // Functions, symbols, undefined: nothing serializable to keep.
+    return TRUNCATION_SUFFIX;
+}
+/** Cap a record's entries; once the shared node budget is spent, signal that keys were dropped. */
+function capRecord(value, budget, depth) {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (budget.nodes >= MAX_OBJECT_NODES) {
+            // Signal explicitly that keys were dropped rather than silently truncating.
+            out[TRUNCATION_SUFFIX] = TRUNCATION_SUFFIX;
+            break;
+        }
+        out[capString(key)] = capValue(item, budget, depth + 1);
+    }
+    return out;
+}
+/**
+ * Cap a value for ingest: strings to 8 KB, the whole value to 500 nodes, nesting
+ * to depth 5 (depth 0 = the top-level value). Over-budget subtrees are replaced
+ * with '...[truncated]'. Pass a shared {@link CapBudget} to count nodes across
+ * several top-level fields of the same payload.
+ */
+export function capValue(value, budget = { nodes: 0 }, depth = 0) {
+    budget.nodes += 1;
+    if (budget.nodes > MAX_OBJECT_NODES)
+        return TRUNCATION_SUFFIX;
+    if (depth > MAX_OBJECT_DEPTH)
+        return TRUNCATION_SUFFIX;
+    if (Array.isArray(value))
+        return value.map((item) => capValue(item, budget, depth + 1));
+    if (isRecord(value))
+        return capRecord(value, budget, depth);
+    return capScalar(value);
+}

package/dist/events/normalize.d.ts

@@ -0,0 +1,36 @@
+import { type Envelope } from "./contract.js";
+/**
+ * Per-source payload → canonical envelope.
+ *
+ * One name-normalizer maps every harness's event name onto the canonical taxonomy
+ * (trim, camelCase→snake_case, hyphens→underscores, lowercase) so 'PreToolUse'
+ * (claude) and 'pre_tool_use' (codex/gemini/cursor) converge. Unrecognized events
+ * become `unknown_event` passthroughs — new harness events never drop data.
+ */
+export interface NormalizeOptions {
+    /** Override receivedAt (ISO string); used when replaying spooled events. */
+    receivedAt?: string;
+    /** The event's unique id (Envelope.id). */
+    id?: string;
+}
+/** Trim + lowercase the agent/source id. */
+export declare function normalizeAgent(source: string): string;
+/**
+ * Map any harness event name onto the canonical snake_case taxonomy:
+ * trims, converts camelCase/PascalCase boundaries to underscores, converts
+ * hyphens/whitespace to underscores, lowercases. Already-canonical names
+ * round-trip unchanged.
+ */
+export declare function normalizeEventName(name: string): string;
+/** The tool input as the harness sent it, before the payload caps: deny rules match on this, never on the capped copy that is forwarded. */
+export declare function uncappedToolInput(raw: Record<string, unknown>): unknown;
+/**
+ * Normalize one raw harness payload into the canonical envelope:
+ * `{ v: 1, event, agent, session, pane, receivedAt, payload }`.
+ *
+ * Known harness fields are mapped onto canonical payload keys (tool, tool_input,
+ * tool_response, cwd); every other field passes through capped so nothing is
+ * silently dropped. Strings > 8192 chars, payloads > 500 nodes and nesting > 5
+ * are truncated with '...[truncated]'.
+ */
+export declare function normalize(source: string, raw: Record<string, unknown>, options?: NormalizeOptions): Envelope;

package/dist/events/normalize.js

@@ -0,0 +1,143 @@
+import { capString, capValue, isCanonicalEvent, UNKNOWN_EVENT, } from "./contract.js";
+const SHARED_FIELDS = {
+    event: ["hook_event_name"],
+    session: ["session_id", "session"],
+};
+const SOURCE_FIELDS = {
+    claude: SHARED_FIELDS,
+    codex: SHARED_FIELDS,
+    // Gemini CLI's own event names (src/clients/definitions.ts GEMINI_EVENTS); it has no subagent stop.
+    gemini: {
+        ...SHARED_FIELDS,
+        aliases: {
+            before_tool: "pre_tool_use",
+            after_tool: "post_tool_use",
+            before_agent: "user_prompt_submit",
+            after_agent: "stop",
+            pre_compress: "pre_compact",
+        },
+    },
+    // Cursor names its session `conversation_id`; only sessionStart also carries a session_id.
+    cursor: {
+        event: SHARED_FIELDS.event,
+        session: ["conversation_id", ...SHARED_FIELDS.session],
+        aliases: { before_submit_prompt: "user_prompt_submit" },
+    },
+    // Hermes plugin hook names (src/clients/hermes-plugin.ts HERMES_EVENTS). on_session_end fires once per
+    // turn and post_approval_response has no canonical twin: both pass through as unknown_event.
+    hermes: {
+        ...SHARED_FIELDS,
+        aliases: {
+            on_session_start: "session_start",
+            on_session_finalize: "session_end",
+            pre_llm_call: "user_prompt_submit",
+            pre_tool_call: "pre_tool_use",
+            post_tool_call: "post_tool_use",
+            pre_approval_request: "permission_request",
+        },
+    },
+};
+const DEFAULT_FIELDS = SHARED_FIELDS;
+/** Keys consumed by the envelope itself; never duplicated into the payload. */
+const RESERVED_KEYS = new Set([
+    "hook_event_name",
+    "event",
+    "session_id",
+    "session",
+    "pane",
+    "pane_key",
+]);
+/** Trim + lowercase the agent/source id. */
+export function normalizeAgent(source) {
+    return source.trim().toLowerCase();
+}
+/**
+ * Map any harness event name onto the canonical snake_case taxonomy:
+ * trims, converts camelCase/PascalCase boundaries to underscores, converts
+ * hyphens/whitespace to underscores, lowercases. Already-canonical names
+ * round-trip unchanged.
+ */
+export function normalizeEventName(name) {
+    return name
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
+        .replace(/[-\s]+/g, "_")
+        .toLowerCase();
+}
+function pick(raw, keys) {
+    for (const key of keys) {
+        if (raw[key] !== undefined)
+            return raw[key];
+    }
+    return undefined;
+}
+function pickString(raw, keys) {
+    const value = pick(raw, keys);
+    return typeof value === "string" ? value : undefined;
+}
+/** The tool input as the harness sent it, before the payload caps: deny rules match on this, never on the capped copy that is forwarded. */
+export function uncappedToolInput(raw) {
+    return pick(raw, ["tool_input", "toolInput"]);
+}
+/** The canonical event: the harness's own name normalized, or unknown_event passthrough. */
+function canonicalEvent(raw, fields) {
+    const rawEvent = pickString(raw, [...fields.event, "event"]);
+    const normalized = rawEvent === undefined ? null : normalizeEventName(rawEvent);
+    const canonical = normalized === null ? null : fields.aliases?.[normalized] ?? normalized;
+    const event = canonical !== null && isCanonicalEvent(canonical) ? canonical : UNKNOWN_EVENT;
+    return { event, canonical };
+}
+/** Map the known harness fields + everything unreserved onto the payload, capped by the shared budget. */
+function canonicalPayload(raw, fields, budget) {
+    const payload = {};
+    const tool = pick(raw, ["tool_name", "tool"]);
+    if (tool !== undefined)
+        payload["tool"] = capValue(tool, budget);
+    const toolInput = pick(raw, ["tool_input", "toolInput"]);
+    if (toolInput !== undefined)
+        payload["tool_input"] = capValue(toolInput, budget);
+    const toolResponse = pick(raw, ["tool_response", "toolResponse"]);
+    if (toolResponse !== undefined)
+        payload["tool_response"] = capValue(toolResponse, budget);
+    const cwd = pickString(raw, ["cwd", "working_dir", "workingDir"]);
+    if (cwd !== undefined)
+        payload["cwd"] = capValue(cwd, budget);
+    for (const [key, value] of Object.entries(raw)) {
+        if (RESERVED_KEYS.has(key) || key in payload || fields.event.includes(key))
+            continue;
+        payload[key] = capValue(value, budget);
+    }
+    return payload;
+}
+/**
+ * Normalize one raw harness payload into the canonical envelope:
+ * `{ v: 1, event, agent, session, pane, receivedAt, payload }`.
+ *
+ * Known harness fields are mapped onto canonical payload keys (tool, tool_input,
+ * tool_response, cwd); every other field passes through capped so nothing is
+ * silently dropped. Strings > 8192 chars, payloads > 500 nodes and nesting > 5
+ * are truncated with '...[truncated]'.
+ */
+export function normalize(source, raw, options = {}) {
+    const fields = SOURCE_FIELDS[normalizeAgent(source)] ?? DEFAULT_FIELDS;
+    const { event, canonical } = canonicalEvent(raw, fields);
+    // One node budget across the whole payload: 500 nodes total, not per field.
+    const budget = { nodes: 0 };
+    const payload = canonicalPayload(raw, fields, budget);
+    if (event === UNKNOWN_EVENT && canonical !== null) {
+        // Preserve which event the harness actually sent (normalized form).
+        payload["original_event"] = canonical;
+    }
+    return {
+        v: 1,
+        event,
+        agent: normalizeAgent(source),
+        // Heedvane requires a session: an event without one is filed under its pane, else "unknown".
+        session: capString(pickString(raw, fields.session) || pickString(raw, ["pane", "pane_key"]) || "unknown"),
+        pane: capString(pickString(raw, ["pane", "pane_key"]) ?? ""),
+        receivedAt: options.receivedAt ?? new Date().toISOString(),
+        payload,
+        ...(options.id === undefined ? {} : { id: options.id }),
+    };
+}

package/dist/guards.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The package's one copy of three repository-owned helpers: `isRecord` (owner:
+ * packages/type-predicates), `errorMessage` (owner:
+ * packages/operator-diagnostics/error-message) and `sha256Hex` (owner: packages/content-digest).
+ * All three owners are `private`
+ * workspace packages, and heedvane-hooks ships standalone through npm/npx with
+ * zero intra-monorepo runtime imports (recorded exception, see
+ * docs/engineering/agent-hooks-architecture.md and
+ * .hermes/plans/2026-10-10_042212-heedvane-agent-hooks.md "Deliberate choices"),
+ * so it cannot depend on them. Every module in this package imports these from
+ * here. Keep the bodies identical to the owners'.
+ */
+/** Non-null objects other than arrays; arrays must not become records with numeric keys. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** The one-line text of a thrown value: an Error's own message, any other value's string form. */
+export declare function errorMessage(thrown: unknown): string;
+/** SHA-256 hex of UTF-8 text, or of exact bytes. */
+export declare function sha256Hex(text: string | Uint8Array): string;

package/dist/guards.js

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+/**
+ * The package's one copy of three repository-owned helpers: `isRecord` (owner:
+ * packages/type-predicates), `errorMessage` (owner:
+ * packages/operator-diagnostics/error-message) and `sha256Hex` (owner: packages/content-digest).
+ * All three owners are `private`
+ * workspace packages, and heedvane-hooks ships standalone through npm/npx with
+ * zero intra-monorepo runtime imports (recorded exception, see
+ * docs/engineering/agent-hooks-architecture.md and
+ * .hermes/plans/2026-10-10_042212-heedvane-agent-hooks.md "Deliberate choices"),
+ * so it cannot depend on them. Every module in this package imports these from
+ * here. Keep the bodies identical to the owners'.
+ */
+/** Non-null objects other than arrays; arrays must not become records with numeric keys. */
+export function isRecord(value) {
+    // eslint-disable-next-line local/no-private-helper-copy -- heedvane-hooks ships standalone through npx (no workspace runtime imports), so it keeps its own copy of isRecord
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The one-line text of a thrown value: an Error's own message, any other value's string form. */
+export function errorMessage(thrown) {
+    // eslint-disable-next-line local/no-private-helper-copy -- heedvane-hooks ships standalone through npx (no workspace runtime imports), so it keeps its own copy of errorMessage
+    return thrown instanceof Error ? thrown.message : String(thrown);
+}
+/** SHA-256 hex of UTF-8 text, or of exact bytes. */
+// eslint-disable-next-line local/no-private-helper-copy -- heedvane-hooks ships standalone through npx (no workspace runtime imports), so it keeps its own copy of sha256Hex
+export function sha256Hex(text) {
+    return createHash("sha256").update(text).digest("hex");
+}

package/dist/heed-file.d.ts

@@ -0,0 +1,67 @@
+/**
+ * heed.yaml — the human-owned control file (schema v1).
+ *
+ * Load with {@link loadHeedFile}; every field is normalized to its default so
+ * downstream code never re-implements the schema. See DEFAULT_HEED_YAML_TEMPLATE
+ * for the commented file `npx heedvane init` writes.
+ */
+export interface HeedListenerConfig {
+    /** 0 = pick a free port at first start (resolved value persists to endpoint.env). */
+    port: number;
+    /** Spool to disk when the listener is unreachable. */
+    spool: boolean;
+}
+export interface HeedInstallConfig {
+    hooks: boolean;
+    skill: boolean;
+    mcp: boolean;
+}
+export interface HeedGatingConfig {
+    mode: "pane" | "always";
+}
+export interface HeedSkillsConfig {
+    /** Deny a skill that is not on the organization's approved list. */
+    enforce: boolean;
+    /** Also require the local SKILL.md to hash to the approved sha256. */
+    strict: boolean;
+    /** No synced approved list, or no listener to check it: let the skill run with a warning, or deny it. */
+    whenUnknown: "allow" | "deny";
+}
+/** The Heedvane backend the listener asks for steering, approved skills and memory. */
+export interface HeedvaneConfig {
+    url: string;
+    steering: boolean;
+    memory: boolean;
+    skills: HeedSkillsConfig;
+}
+export interface HeedFile {
+    schemaVersion: "v1";
+    root: string;
+    listener: HeedListenerConfig;
+    agents: "auto" | string[];
+    install: HeedInstallConfig;
+    gating: HeedGatingConfig;
+    heedvane: HeedvaneConfig;
+}
+/**
+ * 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";
+/**
+ * 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 declare function loadHeedFile(text: string): HeedFile;
+/** `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;
+/**
+ * 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 declare function loadHeedFileAt(path: string, log?: (line: string) => void): HeedFile;
+/** heed.yaml's `heedvane` section under `root`; the template's defaults before init has written one. */
+export declare function heedvaneConfigAt(root: string): HeedvaneConfig;