@cleocode/cleo-os 2026.4.31 → 2026.4.36

package/extensions/cleo-hooks-bridge.js

@@ -0,0 +1,197 @@
+/**
+ * CleoOS CAAMP hooks bridge — Pi event → CLEO hook translation.
+ *
+ * CANONICAL LOCATION: `packages/cleo-os/extensions/cleo-hooks-bridge.ts`
+ *
+ * Installed to: $XDG_DATA_HOME/cleo/extensions/cleo-hooks-bridge.js
+ * Loaded by:    Pi via `--extension <path>` injected by CleoOS cli.ts
+ *
+ * Bridges Pi runtime events to CLEO's CAAMP hook vocabulary so that
+ * CLEO's existing hook handlers (session-hooks, task-hooks, conduit-hooks)
+ * are informed of Pi activity without requiring any changes to the hook
+ * substrate.
+ *
+ * Event → CAAMP mapping:
+ *   Pi `tool_call`          → `cleo memory observe` (PreToolUse)
+ *   Pi `tool_result`        → `cleo memory observe` (PostToolUse)
+ *   Pi `before_agent_start` → `cleo memory observe` (SubagentStart)
+ *
+ * All observations are stored with `--type discovery` and `--sourceType auto`
+ * so they are distinguished from manual observations.
+ *
+ * Design constraints:
+ *   - Best-effort: never crash Pi — all CLI calls wrapped in try/catch
+ *   - NO top-level await; all work inside event handlers
+ *   - Rate-limited: at most 1 observation per event type per 500 ms to
+ *     avoid flooding brain.db with high-frequency tool calls
+ *   - Tool names are sanitised before storage (no shell injection risk
+ *     because we use execFileAsync, not shell)
+ *
+ * @packageDocumentation
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { accentPrimary, textSecondary, ICON_FORGE, } from "./tui-theme.js";
+const execFileAsync = promisify(execFile);
+// ============================================================================
+// Rate-limiting state
+// ============================================================================
+/**
+ * Minimum milliseconds between observations of the same hook type.
+ * Prevents flooding brain.db on high-frequency tool invocations.
+ */
+const RATE_LIMIT_MS = 500;
+/** Tracks the last emission timestamp per hook type key. */
+const lastEmit = {};
+/**
+ * Check whether a hook observation should be emitted, applying rate limiting.
+ *
+ * @param key - A string key identifying the hook type (e.g. "PreToolUse:bash").
+ * @returns `true` if the observation should be emitted now.
+ */
+function shouldEmit(key) {
+    const now = Date.now();
+    const last = lastEmit[key] ?? 0;
+    if (now - last < RATE_LIMIT_MS)
+        return false;
+    lastEmit[key] = now;
+    return true;
+}
+// ============================================================================
+// CAAMP observation helpers
+// ============================================================================
+/**
+ * Sanitise a string for safe inclusion in a CLEO observation title/text.
+ *
+ * Trims and limits length to avoid oversized brain.db entries.
+ *
+ * @param raw - The raw string to sanitise.
+ * @param maxLen - Maximum character length (default 120).
+ * @returns The sanitised string.
+ */
+function sanitise(raw, maxLen = 120) {
+    return raw.trim().slice(0, maxLen);
+}
+/**
+ * Extract a human-readable summary from a `tool_call` event.
+ *
+ * @param event - The Pi tool_call event.
+ * @returns A brief description of the tool invocation.
+ */
+function summariseToolCall(event) {
+    const toolName = event.toolName ?? "unknown";
+    if (toolName === "bash") {
+        const cmd = event.input?.command ?? "";
+        return `bash: ${sanitise(cmd, 80)}`;
+    }
+    if (toolName === "edit" || toolName === "write" || toolName === "read") {
+        const path = event.input?.file_path ?? "";
+        return `${toolName}: ${sanitise(path, 80)}`;
+    }
+    return toolName;
+}
+/**
+ * Fire a CAAMP observation via `cleo memory observe`.
+ *
+ * Best-effort: any error is silently swallowed to never crash Pi.
+ *
+ * @param text - Observation text to store.
+ * @param title - Short title for the observation.
+ * @param cwd - Project root directory.
+ */
+function fireObservation(text, title, cwd) {
+    execFileAsync("cleo", [
+        "memory", "observe",
+        "--title", sanitise(title, 120),
+        "--type", "discovery",
+        "--sourceType", "auto",
+        "--agent", "pi-hooks-bridge",
+        sanitise(text, 500),
+    ], { timeout: 5_000, cwd }).catch(() => {
+        // Intentionally swallowed — best-effort only
+    });
+}
+// ============================================================================
+// Status bar tracking
+// ============================================================================
+/** Count of hooks fired this session for the status bar display. */
+let hooksFired = 0;
+// ============================================================================
+// Pi extension factory
+// ============================================================================
+/**
+ * Pi extension factory for the CAAMP hooks bridge.
+ *
+ * Registers:
+ *   - `tool_call` → PreToolUse observation
+ *   - `tool_result` → PostToolUse observation
+ *   - `before_agent_start` → SubagentStart observation
+ *
+ * @param pi - The Pi extension API instance.
+ */
+export default function (pi) {
+    // ── session_start: reset counters ──────────────────────────────────────
+    pi.on("session_start", async (_event, ctx) => {
+        hooksFired = 0;
+        // Clear rate-limit state for fresh session
+        for (const key of Object.keys(lastEmit)) {
+            delete lastEmit[key];
+        }
+        if (ctx.hasUI) {
+            ctx.ui.setStatus("cleo-hooks-bridge", `${accentPrimary(ICON_FORGE)} hooks: 0`);
+        }
+    });
+    // ── tool_call → PreToolUse ─────────────────────────────────────────────
+    pi.on("tool_call", async (event, ctx) => {
+        const toolName = event.toolName ?? "unknown";
+        const rateKey = `PreToolUse:${toolName}`;
+        if (!shouldEmit(rateKey))
+            return {};
+        const summary = summariseToolCall(event);
+        fireObservation(`CAAMP PreToolUse — Pi invoked tool: ${summary}`, `PreToolUse: ${toolName}`, ctx.cwd);
+        hooksFired++;
+        if (ctx.hasUI) {
+            ctx.ui.setStatus("cleo-hooks-bridge", `${textSecondary(ICON_FORGE)} hooks: ${hooksFired}`);
+        }
+        // Do not modify the tool call
+        return {};
+    });
+    // ── tool_result → PostToolUse ──────────────────────────────────────────
+    pi.on("tool_result", async (event, ctx) => {
+        const toolCallId = event.toolCallId ?? "unknown";
+        const rateKey = `PostToolUse:${toolCallId.slice(0, 12)}`;
+        if (!shouldEmit(rateKey))
+            return {};
+        const isError = event.isError ? " (error)" : "";
+        fireObservation(`CAAMP PostToolUse — tool result received${isError}: id=${toolCallId.slice(0, 16)}`, `PostToolUse: result${isError}`, ctx.cwd);
+        hooksFired++;
+        if (ctx.hasUI) {
+            ctx.ui.setStatus("cleo-hooks-bridge", `${textSecondary(ICON_FORGE)} hooks: ${hooksFired}`);
+        }
+        return {};
+    });
+    // ── before_agent_start → SubagentStart ────────────────────────────────
+    pi.on("before_agent_start", async (event, ctx) => {
+        const agentName = event.agentName ??
+            event.agentDef?.name ??
+            "unknown-agent";
+        const rateKey = `SubagentStart:${agentName}`;
+        if (!shouldEmit(rateKey))
+            return {};
+        fireObservation(`CAAMP SubagentStart — Pi spawned agent: ${sanitise(agentName)}`, `SubagentStart: ${sanitise(agentName, 60)}`, ctx.cwd);
+        hooksFired++;
+        if (ctx.hasUI) {
+            ctx.ui.setStatus("cleo-hooks-bridge", `${textSecondary(ICON_FORGE)} hooks: ${hooksFired}`);
+        }
+        // Do not modify the system prompt — other extensions handle that
+        return {};
+    });
+    // ── session_shutdown: clear state ──────────────────────────────────────
+    pi.on("session_shutdown", async () => {
+        hooksFired = 0;
+        for (const key of Object.keys(lastEmit)) {
+            delete lastEmit[key];
+        }
+    });
+}
+//# sourceMappingURL=cleo-hooks-bridge.js.map

package/extensions/cleo-hooks-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleo-hooks-bridge.js","sourceRoot":"","sources":["cleo-hooks-bridge.ts"],"names":[],"mappings":"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"}

package/extensions/cleo-hooks-bridge.ts

@@ -0,0 +1,272 @@
+/**
+ * CleoOS CAAMP hooks bridge — Pi event → CLEO hook translation.
+ *
+ * CANONICAL LOCATION: `packages/cleo-os/extensions/cleo-hooks-bridge.ts`
+ *
+ * Installed to: $XDG_DATA_HOME/cleo/extensions/cleo-hooks-bridge.js
+ * Loaded by:    Pi via `--extension <path>` injected by CleoOS cli.ts
+ *
+ * Bridges Pi runtime events to CLEO's CAAMP hook vocabulary so that
+ * CLEO's existing hook handlers (session-hooks, task-hooks, conduit-hooks)
+ * are informed of Pi activity without requiring any changes to the hook
+ * substrate.
+ *
+ * Event → CAAMP mapping:
+ *   Pi `tool_call`          → `cleo memory observe` (PreToolUse)
+ *   Pi `tool_result`        → `cleo memory observe` (PostToolUse)
+ *   Pi `before_agent_start` → `cleo memory observe` (SubagentStart)
+ *
+ * All observations are stored with `--type discovery` and `--sourceType auto`
+ * so they are distinguished from manual observations.
+ *
+ * Design constraints:
+ *   - Best-effort: never crash Pi — all CLI calls wrapped in try/catch
+ *   - NO top-level await; all work inside event handlers
+ *   - Rate-limited: at most 1 observation per event type per 500 ms to
+ *     avoid flooding brain.db with high-frequency tool calls
+ *   - Tool names are sanitised before storage (no shell injection risk
+ *     because we use execFileAsync, not shell)
+ *
+ * @packageDocumentation
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ToolCallEvent,
+  ToolResultEvent,
+  BeforeAgentStartEvent,
+} from "@mariozechner/pi-coding-agent";
+import {
+  accentPrimary,
+  textSecondary,
+  ICON_FORGE,
+} from "./tui-theme.js";
+
+const execFileAsync = promisify(execFile);
+
+// ============================================================================
+// Rate-limiting state
+// ============================================================================
+
+/**
+ * Minimum milliseconds between observations of the same hook type.
+ * Prevents flooding brain.db on high-frequency tool invocations.
+ */
+const RATE_LIMIT_MS = 500;
+
+/** Tracks the last emission timestamp per hook type key. */
+const lastEmit: Record<string, number> = {};
+
+/**
+ * Check whether a hook observation should be emitted, applying rate limiting.
+ *
+ * @param key - A string key identifying the hook type (e.g. "PreToolUse:bash").
+ * @returns `true` if the observation should be emitted now.
+ */
+function shouldEmit(key: string): boolean {
+  const now = Date.now();
+  const last = lastEmit[key] ?? 0;
+  if (now - last < RATE_LIMIT_MS) return false;
+  lastEmit[key] = now;
+  return true;
+}
+
+// ============================================================================
+// CAAMP observation helpers
+// ============================================================================
+
+/**
+ * Sanitise a string for safe inclusion in a CLEO observation title/text.
+ *
+ * Trims and limits length to avoid oversized brain.db entries.
+ *
+ * @param raw - The raw string to sanitise.
+ * @param maxLen - Maximum character length (default 120).
+ * @returns The sanitised string.
+ */
+function sanitise(raw: string, maxLen = 120): string {
+  return raw.trim().slice(0, maxLen);
+}
+
+/**
+ * Extract a human-readable summary from a `tool_call` event.
+ *
+ * @param event - The Pi tool_call event.
+ * @returns A brief description of the tool invocation.
+ */
+function summariseToolCall(event: ToolCallEvent): string {
+  const toolName = event.toolName ?? "unknown";
+  if (toolName === "bash") {
+    const cmd = (event as { input?: { command?: string } }).input?.command ?? "";
+    return `bash: ${sanitise(cmd, 80)}`;
+  }
+  if (toolName === "edit" || toolName === "write" || toolName === "read") {
+    const path = (event as { input?: { file_path?: string } }).input?.file_path ?? "";
+    return `${toolName}: ${sanitise(path, 80)}`;
+  }
+  return toolName;
+}
+
+/**
+ * Fire a CAAMP observation via `cleo memory observe`.
+ *
+ * Best-effort: any error is silently swallowed to never crash Pi.
+ *
+ * @param text - Observation text to store.
+ * @param title - Short title for the observation.
+ * @param cwd - Project root directory.
+ */
+function fireObservation(text: string, title: string, cwd: string): void {
+  execFileAsync(
+    "cleo",
+    [
+      "memory", "observe",
+      "--title", sanitise(title, 120),
+      "--type", "discovery",
+      "--sourceType", "auto",
+      "--agent", "pi-hooks-bridge",
+      sanitise(text, 500),
+    ],
+    { timeout: 5_000, cwd },
+  ).catch(() => {
+    // Intentionally swallowed — best-effort only
+  });
+}
+
+// ============================================================================
+// Status bar tracking
+// ============================================================================
+
+/** Count of hooks fired this session for the status bar display. */
+let hooksFired = 0;
+
+// ============================================================================
+// Pi extension factory
+// ============================================================================
+
+/**
+ * Pi extension factory for the CAAMP hooks bridge.
+ *
+ * Registers:
+ *   - `tool_call` → PreToolUse observation
+ *   - `tool_result` → PostToolUse observation
+ *   - `before_agent_start` → SubagentStart observation
+ *
+ * @param pi - The Pi extension API instance.
+ */
+export default function (pi: ExtensionAPI): void {
+  // ── session_start: reset counters ──────────────────────────────────────
+  pi.on("session_start", async (_event: unknown, ctx: ExtensionContext) => {
+    hooksFired = 0;
+    // Clear rate-limit state for fresh session
+    for (const key of Object.keys(lastEmit)) {
+      delete lastEmit[key];
+    }
+    if (ctx.hasUI) {
+      ctx.ui.setStatus(
+        "cleo-hooks-bridge",
+        `${accentPrimary(ICON_FORGE)} hooks: 0`,
+      );
+    }
+  });
+
+  // ── tool_call → PreToolUse ─────────────────────────────────────────────
+  pi.on(
+    "tool_call",
+    async (event: ToolCallEvent, ctx: ExtensionContext) => {
+      const toolName = event.toolName ?? "unknown";
+      const rateKey = `PreToolUse:${toolName}`;
+
+      if (!shouldEmit(rateKey)) return {};
+
+      const summary = summariseToolCall(event);
+      fireObservation(
+        `CAAMP PreToolUse — Pi invoked tool: ${summary}`,
+        `PreToolUse: ${toolName}`,
+        ctx.cwd,
+      );
+
+      hooksFired++;
+      if (ctx.hasUI) {
+        ctx.ui.setStatus(
+          "cleo-hooks-bridge",
+          `${textSecondary(ICON_FORGE)} hooks: ${hooksFired}`,
+        );
+      }
+
+      // Do not modify the tool call
+      return {};
+    },
+  );
+
+  // ── tool_result → PostToolUse ──────────────────────────────────────────
+  pi.on(
+    "tool_result",
+    async (event: ToolResultEvent, ctx: ExtensionContext) => {
+      const toolCallId = event.toolCallId ?? "unknown";
+      const rateKey = `PostToolUse:${toolCallId.slice(0, 12)}`;
+
+      if (!shouldEmit(rateKey)) return {};
+
+      const isError = event.isError ? " (error)" : "";
+      fireObservation(
+        `CAAMP PostToolUse — tool result received${isError}: id=${toolCallId.slice(0, 16)}`,
+        `PostToolUse: result${isError}`,
+        ctx.cwd,
+      );
+
+      hooksFired++;
+      if (ctx.hasUI) {
+        ctx.ui.setStatus(
+          "cleo-hooks-bridge",
+          `${textSecondary(ICON_FORGE)} hooks: ${hooksFired}`,
+        );
+      }
+
+      return {};
+    },
+  );
+
+  // ── before_agent_start → SubagentStart ────────────────────────────────
+  pi.on(
+    "before_agent_start",
+    async (event: BeforeAgentStartEvent, ctx: ExtensionContext) => {
+      const agentName =
+        (event as { agentName?: string }).agentName ??
+        (event as { agentDef?: { name?: string } }).agentDef?.name ??
+        "unknown-agent";
+
+      const rateKey = `SubagentStart:${agentName}`;
+
+      if (!shouldEmit(rateKey)) return {};
+
+      fireObservation(
+        `CAAMP SubagentStart — Pi spawned agent: ${sanitise(agentName)}`,
+        `SubagentStart: ${sanitise(agentName, 60)}`,
+        ctx.cwd,
+      );
+
+      hooksFired++;
+      if (ctx.hasUI) {
+        ctx.ui.setStatus(
+          "cleo-hooks-bridge",
+          `${textSecondary(ICON_FORGE)} hooks: ${hooksFired}`,
+        );
+      }
+
+      // Do not modify the system prompt — other extensions handle that
+      return {};
+    },
+  );
+
+  // ── session_shutdown: clear state ──────────────────────────────────────
+  pi.on("session_shutdown", async () => {
+    hooksFired = 0;
+    for (const key of Object.keys(lastEmit)) {
+      delete lastEmit[key];
+    }
+  });
+}