@massa-ai/claude-plugin 1.6.0

package/hooks/_pin.sh

@@ -0,0 +1,64 @@
+#!/bin/sh
+# Shared helper: per-session project id pinning for massa-ai hook scripts.
+#
+# Source this AFTER stdin capture (single-read constraint — plan-critic C3),
+# never before: this helper runs no stdin reads, but callers must have already
+# consumed the hook payload so the POST body stays intact.
+#
+#   massa_ai_pin_project_id <session_id> <cwd>
+#
+# echoes the pinned project id. First event of a session computes the id
+# (MASSA_AI_PROJECT_ID env override > git toplevel basename > cwd basename)
+# and writes the pin file; later events of the same session read it back, so a
+# hook fired from a subdirectory keeps the session's original attribution.
+# Without a session id there is nothing to key on — the computed id is echoed
+# without any pin I/O. Silent-degrade: git absence or pin-file failure falls
+# back to the computed id; this helper never fails the caller.
+#
+# Pin files live under ${TMPDIR:-/tmp}/massa-ai-hooks/<sanitized-session_id>.
+
+massa_ai_pin_project_id() {
+  _mpin_session="$1"
+  _mpin_cwd="$2"
+
+  # Existing pin wins: read it back without recomputing. Sanitization is a
+  # lossy but filesystem-safe encoding (distinct ids can collide; real Claude
+  # session ids are UUIDs, so this is accepted). "." / ".." are skipped: they
+  # name directories, never valid pin files.
+  if [ -n "$_mpin_session" ]; then
+    _mpin_dir="${TMPDIR:-/tmp}/massa-ai-hooks"
+    _mpin_safe=$(printf '%s' "$_mpin_session" | tr -c 'A-Za-z0-9._-' '_')
+    case "$_mpin_safe" in
+      .|..) _mpin_file="" ;;
+      *) _mpin_file="$_mpin_dir/$_mpin_safe" ;;
+    esac
+    if [ -n "$_mpin_file" ] && [ -f "$_mpin_file" ]; then
+      _mpin_pinned=$(cat "$_mpin_file" 2>/dev/null)
+      if [ -n "$_mpin_pinned" ]; then
+        printf '%s' "$_mpin_pinned"
+        return 0
+      fi
+    fi
+  fi
+
+  # Compute the candidate id: env override > git toplevel basename > cwd basename.
+  _mpin_computed="${MASSA_AI_PROJECT_ID:-}"
+  if [ -z "$_mpin_computed" ]; then
+    _mpin_root=$(git -C "$_mpin_cwd" rev-parse --show-toplevel 2>/dev/null) || _mpin_root=""
+    if [ -n "$_mpin_root" ]; then
+      _mpin_computed=$(basename "$_mpin_root")
+    else
+      _mpin_computed=$(basename "$_mpin_cwd")
+    fi
+  fi
+
+  # Pin for later events of this session (best effort). stderr is redirected
+  # before stdout so a redirect-open failure (e.g. unwritable dir) stays silent.
+  if [ -n "$_mpin_session" ] && [ -n "$_mpin_file" ]; then
+    mkdir -p "$_mpin_dir" 2>/dev/null || true
+    printf '%s' "$_mpin_computed" 2>/dev/null > "$_mpin_file" || true
+  fi
+
+  printf '%s' "$_mpin_computed"
+  return 0
+}

package/hooks/_post.sh

@@ -0,0 +1,77 @@
+#!/bin/sh
+# Shared helper: POST a lifecycle observation to the massa-ai hook endpoint.
+# Source this from the per-hook scripts after setting:
+#   EVENT  — the lifecycle event kind
+#   PROJECT_ID — the projectId (from env or cwd basename)
+# The Claude Code hook payload is read from stdin as JSON and forwarded as the
+# observation `payload`. The session id is lifted from the payload to the
+# top-level `sessionId` field so rows are session-scoped (NULL when absent).
+# Silent-degrade: never blocks the agent (exit 0, no stdout).
+#
+# Env:
+#   MASSA_AI_API_BASE  — API base URL (default http://localhost:3333)
+#   MASSA_AI_API_KEY   — optional API key (x-api-key header)
+#   MASSA_AI_PROJECT_ID — optional explicit projectId (else git toplevel
+#                             basename, else cwd basename; pinned per session)
+
+_massa_ai_base="${MASSA_AI_API_BASE:-http://localhost:3333}"
+_massa_ai_url="$_massa_ai_base/api/v1/hook"
+
+# Read the Claude Code hook payload from stdin (JSON) — may be empty.
+_massa_ai_raw=""
+if [ -t 0 ]; then
+  _massa_ai_raw=""
+else
+  _massa_ai_raw=$(cat)
+fi
+
+# Lift the session id to the top-level `sessionId` field. Claude Code sends
+# "session_id"; accept "sessionId" too. jq preferred, sed fallback otherwise.
+_massa_ai_session=""
+if [ -n "$_massa_ai_raw" ] && command -v jq >/dev/null 2>&1; then
+  _massa_ai_session=$(printf '%s' "$_massa_ai_raw" | jq -r '.session_id // .sessionId // ""' 2>/dev/null)
+elif [ -n "$_massa_ai_raw" ]; then
+  _massa_ai_session=$(printf '%s' "$_massa_ai_raw" | sed -n 's/.*"session_id"[: ]*"*\([^",}]*\).*/\1/p' 2>/dev/null)
+fi
+
+# Whitespace-stripped copy for the emptiness check + payload embed. When there
+# is no payload (interactive TTY, empty stdin, or whitespace only), skip the
+# POST entirely: the server rejects an empty payload object
+# ("payload must be a non-empty object" → 400), and a fire-and-forget hook
+# has nothing useful to record without one. Exit 0 so the agent is never blocked.
+_massa_ai_stdin=$(printf '%s' "$_massa_ai_raw" | tr -d '[:space:]')
+[ -z "$_massa_ai_stdin" ] && exit 0
+
+# Resolve the project id through the per-session pin (M45/HAR-04). This runs
+# AFTER the stdin capture above — the pin helper never touches stdin, and the
+# POST body must stay intact (single-read constraint). A missing helper falls
+# back to today's env/basename behavior so silent-degrade is preserved.
+_massa_ai_pin_lib="$(dirname "$0")/_pin.sh"
+if [ -f "$_massa_ai_pin_lib" ]; then
+  . "$_massa_ai_pin_lib"
+  _massa_ai_project=$(massa_ai_pin_project_id "$_massa_ai_session" "$PWD")
+else
+  _massa_ai_project="${MASSA_AI_PROJECT_ID:-$(basename "$PWD")}"
+fi
+
+# Conditionally include the top-level sessionId field. Omit it entirely when
+# absent so the server stores NULL (preserves prior behavior for payloads
+# without a session id, rather than storing an empty string).
+_massa_ai_session_field=""
+if [ -n "$_massa_ai_session" ]; then
+  _massa_ai_session_field=$(printf ',"sessionId":"%s"' "$_massa_ai_session")
+fi
+
+# Build the observation body. We trust the host payload is already valid JSON
+# (Claude Code emits JSON), so we only need to drop it verbatim into payload.
+_massa_ai_body=$(printf '{"event":"%s","projectId":"%s"%s,"payload":%s}' \
+  "$EVENT" "$_massa_ai_project" "$_massa_ai_session_field" "$_massa_ai_stdin")
+
+# Silent-degrade: if curl is missing or the endpoint is down, just exit 0.
+command -v curl >/dev/null 2>&1 || exit 0
+curl -sS -m 2 -o /dev/null \
+  -H "Content-Type: application/json" \
+  ${MASSA_AI_API_KEY:+-H "x-api-key: $MASSA_AI_API_KEY"} \
+  -X POST "$_massa_ai_url" \
+  --data "$_massa_ai_body" >/dev/null 2>&1 || true
+exit 0

package/hooks/hooks.json

@@ -0,0 +1,54 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/massa-ai-hook.ts\" session-start"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/massa-ai-hook.ts\" user-prompt-submit"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/massa-ai-hook.ts\" post-tool-use"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/massa-ai-hook.ts\" pre-compact"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run \"${CLAUDE_PLUGIN_ROOT}/hooks/massa-ai-hook.ts\" stop"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/massa-ai-hook.ts

@@ -0,0 +1,298 @@
+#!/usr/bin/env bun
+/**
+ * massa-ai-hook — single typed Bun binary replacing 7 shell hook scripts.
+ *
+ * Wave 6 N30 (T20): reads JSON from stdin (Bun-native, no jq), resolves the
+ * project id through the per-session pin, and POSTs a lifecycle observation
+ * to the massa-ai hook endpoint. Silent-degrade: never blocks the agent
+ * (exit 0, no stdout).
+ *
+ * Subcommands (Claude Code hook event types):
+ *   session-start      → event: "session-start"
+ *   user-prompt-submit  → event: "user-prompt"
+ *   post-tool-use       → event: "post-tool-use"
+ *   pre-compact         → SPECIAL: TWO POSTs (observation + compact-snapshot)
+ *   stop                → event: "session-end"
+ *
+ * CRITICAL (pre-mortem F3): pre-compact does TWO POSTs:
+ *   (1) observation to /api/v1/hook (3s timeout, observation body
+ *       {event, projectId, sessionId, cwd, payload})
+ *   (2) snapshot to /api/v1/hook/compact-snapshot (5s timeout, snapshot body
+ *       {sessionId, projectId, persist, cwd})
+ *   All other subcommands: single POST to /api/v1/hook (2s timeout).
+ *
+ * Pin resolution order (ported from _pin.sh):
+ *   existing pin → env (MASSA_AI_PROJECT_ID) → git toplevel basename → cwd basename
+ *
+ * Terminal stdin (no pipe) → exit 0, no POST (same as shell [ -t 0 ] check).
+ */
+
+import { spawnSync } from "child_process";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, fstatSync } from "fs";
+import path from "path";
+
+// ── Event type mapping ──────────────────────────────────────────────────────
+
+export const EVENT_MAP: Record<string, string> = {
+  "session-start": "session-start",
+  "user-prompt-submit": "user-prompt",
+  "pre-tool-use": "pre-tool-use",
+  "post-tool-use": "post-tool-use",
+  "pre-compact": "pre-compact",
+  stop: "session-end",
+};
+
+// ── Pin resolution (ported from _pin.sh) ─────────────────────────────────────
+
+export function sanitizeSessionId(sessionId: string): string {
+  return sessionId.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+export function getPinDir(): string {
+  return `${process.env.TMPDIR || "/tmp"}/massa-ai-hooks`;
+}
+
+export function getPinFile(sessionId: string): string | null {
+  if (!sessionId) return null;
+  const safe = sanitizeSessionId(sessionId);
+  if (safe === "." || safe === "..") return null;
+  return path.join(getPinDir(), safe);
+}
+
+export function resolveProjectId(sessionId: string, cwd: string): string {
+  // 1. Existing pin wins
+  if (sessionId) {
+    const pinFile = getPinFile(sessionId);
+    if (pinFile) {
+      try {
+        if (existsSync(pinFile)) {
+          const pinned = readFileSync(pinFile, "utf8").trim();
+          if (pinned) return pinned;
+        }
+      } catch {
+        // fall through to compute
+      }
+    }
+  }
+
+  // 2. Compute: env override > git toplevel basename > cwd basename
+  let computed = process.env.MASSA_AI_PROJECT_ID || "";
+  if (!computed) {
+    try {
+      const result = spawnSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+        encoding: "utf8",
+        timeout: 2000,
+      });
+      const root = result.stdout?.trim();
+      if (root) {
+        computed = path.basename(root);
+      }
+    } catch {
+      // git not available
+    }
+    if (!computed) {
+      computed = path.basename(cwd);
+    }
+  }
+
+  // 3. Write pin for later events of this session (best effort)
+  if (sessionId) {
+    const pinFile = getPinFile(sessionId);
+    if (pinFile) {
+      try {
+        mkdirSync(getPinDir(), { recursive: true });
+        writeFileSync(pinFile, computed, { encoding: "utf8" });
+      } catch {
+        // silent-degrade: pin write failure is non-fatal
+      }
+    }
+  }
+
+  return computed;
+}
+
+// ── Stdin reading ───────────────────────────────────────────────────────────
+
+export function readStdin(): string {
+  // Terminal stdin (no pipe) → exit 0, no POST (same as shell [ -t 0 ] check)
+  try {
+    const stats = fstatSync(0);
+    if (stats && stats.isCharacterDevice()) {
+      return ""; // terminal stdin → no payload
+    }
+  } catch {
+    // stat failed — assume no stdin available
+    return "";
+  }
+
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+// ── POST helper ─────────────────────────────────────────────────────────────
+
+export function postObservation(
+  url: string,
+  body: Record<string, unknown>,
+  timeoutMs: number,
+  hookType: string = "unknown",
+): Promise<void> {
+  // Fire-and-forget with bounded timeout; never rejects (silent-degrade).
+  // Returned promise lets main() await POSTs before process.exit so the
+  // event loop doesn't tear down pending sockets mid-flight. The caller's
+  // exit is still bounded by timeoutMs — never blocks the agent longer than
+  // the configured POST timeout.
+  try {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    const apiKey = process.env.MASSA_AI_API_KEY;
+    if (apiKey) {
+      headers["x-api-key"] = apiKey;
+    }
+
+    const startMs = Date.now();
+
+    return fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+      .then(() => {
+        // Breadcrumb-on-fire (W7-13): log to stderr when POST takes >80% of deadline.
+        const elapsedMs = Date.now() - startMs;
+        const pct = (elapsedMs / timeoutMs) * 100;
+        if (pct > 80) {
+          process.stderr.write(
+            JSON.stringify({
+              type: "breadcrumb",
+              hook: hookType,
+              elapsed: elapsedMs,
+              deadline: timeoutMs,
+              pct: Math.round(pct * 100) / 100,
+            }) + "\n",
+          );
+        }
+        // response body discarded; fire-and-forget
+      })
+      .catch((err) => {
+        // Breadcrumb-on-fire (W7-13): log deadline-on-fire on timeout.
+        const elapsedMs = Date.now() - startMs;
+        const isTimeout =
+          err instanceof DOMException &&
+          (err.name === "TimeoutError" || err.name === "AbortError");
+        if (isTimeout) {
+          process.stderr.write(
+            JSON.stringify({
+              type: "deadline-on-fire",
+              hook: hookType,
+              elapsed: elapsedMs,
+              deadline: timeoutMs,
+              reason: "timeout",
+            }) + "\n",
+          );
+        }
+        // silent-degrade: network failure is non-fatal
+      });
+  } catch {
+    // silent-degrade: fetch unavailable or immediate error is non-fatal
+    return Promise.resolve();
+  }
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+export async function main(stdinInput?: string): Promise<void> {
+  const subcommand = process.argv[2];
+  if (!subcommand || !EVENT_MAP[subcommand]) {
+    // Unknown or missing subcommand → exit 0 (silent-degrade)
+    return;
+  }
+
+  const rawStdin = stdinInput ?? readStdin();
+  // Whitespace-stripped check: empty payload → no POST (server rejects empty payload)
+  const stdinStripped = rawStdin.trim();
+  if (!stdinStripped) {
+    return;
+  }
+
+  // Parse JSON (Bun-native, no jq). Malformed JSON → exit 0, no POST.
+  let payload: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(stdinStripped);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return;
+    }
+    payload = parsed as Record<string, unknown>;
+  } catch {
+    // Malformed JSON → exit 0, no POST (same as shell jq failure)
+    return;
+  }
+
+  const event = EVENT_MAP[subcommand]!;
+  const cwd = process.cwd();
+
+  // Extract session id from payload (Claude Code sends "session_id"; accept "sessionId" too)
+  const sessionId =
+    (typeof payload.session_id === "string" ? payload.session_id : "") ||
+    (typeof payload.sessionId === "string" ? payload.sessionId : "") ||
+    "unknown";
+
+  const projectId = resolveProjectId(sessionId, cwd);
+
+  const baseUrl = process.env.MASSA_AI_API_BASE || "http://localhost:3333";
+  const hookUrl = `${baseUrl}/api/v1/hook`;
+
+  if (subcommand === "pre-compact") {
+    // CRITICAL (F3): pre-compact does TWO POSTs
+    // 1. Observation to /api/v1/hook (3s timeout, observation body)
+    const obsBody = {
+      event,
+      projectId,
+      sessionId,
+      cwd,
+      payload,
+    };
+    const obsP = postObservation(hookUrl, obsBody, 3000, subcommand);
+
+    // 2. Snapshot to /api/v1/hook/compact-snapshot (5s timeout, snapshot body)
+    const snapshotUrl = `${baseUrl}/api/v1/hook/compact-snapshot`;
+    const snapBody = {
+      sessionId,
+      projectId,
+      persist: true,
+      cwd,
+    };
+    const snapP = postObservation(snapshotUrl, snapBody, 5000, "compact-snapshot");
+
+    // Await both POSTs (bounded by their timeouts) before exit so the event
+    // loop doesn't tear down pending sockets. Silent-degrade: any rejection
+    // is swallowed inside postObservation; exit is still 0.
+    await Promise.all([obsP, snapP]);
+  } else {
+    // All other subcommands: single POST to /api/v1/hook (2s timeout, observation body)
+    // The body carries projectId (caller), sessionId, and cwd so the server-
+    // side AttributionResolver can run its explicit→sticky→containment→
+    // verbatim chain (AC6). The binary does NOT replicate that logic; it
+    // sends the raw inputs for server-side resolution.
+    const sessionField = sessionId && sessionId !== "unknown" ? { sessionId } : {};
+    const obsBody = {
+      event,
+      projectId,
+      ...sessionField,
+      cwd,
+      payload,
+    };
+    await postObservation(hookUrl, obsBody, 2000, subcommand);
+  }
+
+  // Always exit 0 (silent-degrade: never blocks the agent)
+}
+
+if (import.meta.main) {
+  main().catch(() => process.exit(0));
+}

package/hooks/post-tool-use.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Claude Code PostToolUse hook → massa-ai observation (event: post-tool-use).
+EVENT="post-tool-use"
+. "$(dirname "$0")/_post.sh"

package/hooks/pre-compact.sh

@@ -0,0 +1,70 @@
+#!/bin/sh
+# Claude Code PreCompact hook → massa-ai compaction snapshot.
+#
+# Emits a `pre-compact` lifecycle observation AND triggers the compact_snapshot
+# endpoint to build a bounded, reference-based table-of-contents snapshot of
+# the current session's observations. The snapshot provides zero-loss session
+# continuity: raw events stay in the store; the snapshot just points to them.
+#
+# Claude Code passes the session id in the hook payload JSON on stdin.
+# Silent-degrade: never blocks the agent (exit 0, no stdout).
+
+_massa_ai_base="${MASSA_AI_API_BASE:-http://localhost:3333}"
+
+# Read the Claude Code hook payload from stdin (JSON) — may be empty.
+_massa_ai_stdin=""
+if [ -t 0 ]; then
+  _massa_ai_stdin="{}"
+else
+  _massa_ai_stdin=$(cat)
+fi
+[ -z "$_massa_ai_stdin" ] && _massa_ai_stdin="{}"
+
+# Extract session id from the payload (Claude Code provides "session_id").
+# Use a tiny sed/grep fallback if jq is unavailable.
+_massa_ai_session=""
+if command -v jq >/dev/null 2>&1; then
+  _massa_ai_session=$(printf '%s' "$_massa_ai_stdin" | jq -r '.session_id // .sessionId // ""' 2>/dev/null)
+else
+  _massa_ai_session=$(printf '%s' "$_massa_ai_stdin" | sed -n 's/.*"session_id"[: ]*"*\([^",}]*\).*/\1/p' 2>/dev/null)
+fi
+# Resolve the project id through the per-session pin (M45/HAR-04) — AFTER the
+# stdin capture above (single-read constraint; the pin helper never reads
+# stdin). A missing helper falls back to today's env/basename behavior.
+_massa_ai_pin_lib="$(dirname "$0")/_pin.sh"
+if [ -f "$_massa_ai_pin_lib" ]; then
+  . "$_massa_ai_pin_lib"
+  _massa_ai_project=$(massa_ai_pin_project_id "$_massa_ai_session" "$PWD")
+else
+  _massa_ai_project="${MASSA_AI_PROJECT_ID:-$(basename "$PWD")}"
+fi
+
+[ -z "$_massa_ai_session" ] && _massa_ai_session="unknown"
+
+# 1. Emit the pre-compact lifecycle observation (backward-compatible with the
+#    existing hook ingestion pipeline). cwd travels on the wire so the server
+#    attributes both this obs and the compact-snapshot consistently (M45/HAR-01
+#    sibling-divergence guard).
+_massa_ai_obs_body=$(printf '{"event":"pre-compact","projectId":"%s","sessionId":"%s","cwd":"%s","payload":%s}' \
+  "$_massa_ai_project" "$_massa_ai_session" "$PWD" "$_massa_ai_stdin")
+
+command -v curl >/dev/null 2>&1 || exit 0
+curl -sS -m 3 -o /dev/null \
+  -H "Content-Type: application/json" \
+  ${MASSA_AI_API_KEY:+-H "x-api-key: $MASSA_AI_API_KEY"} \
+  -X POST "$_massa_ai_base/api/v1/hook" \
+  --data "$_massa_ai_obs_body" >/dev/null 2>&1 || true
+
+# 2. Trigger the compact_snapshot endpoint to build + persist the snapshot.
+#    cwd travels on the wire so server-side attribution containment can map the
+#    session to its registered workspace (M45/HAR-01).
+_massa_ai_snap_body=$(printf '{"sessionId":"%s","projectId":"%s","persist":true,"cwd":"%s"}' \
+  "$_massa_ai_session" "$_massa_ai_project" "$PWD")
+
+curl -sS -m 5 -o /dev/null \
+  -H "Content-Type: application/json" \
+  ${MASSA_AI_API_KEY:+-H "x-api-key: $MASSA_AI_API_KEY"} \
+  -X POST "$_massa_ai_base/api/v1/hook/compact-snapshot" \
+  --data "$_massa_ai_snap_body" >/dev/null 2>&1 || true
+
+exit 0

package/hooks/session-start.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Claude Code SessionStart hook → massa-ai observation (event: session-start).
+# Wire in .claude/settings.json under hooks.SessionStart.
+EVENT="session-start"
+. "$(dirname "$0")/_post.sh"

package/hooks/stop.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Claude Code Stop hook → massa-ai observation (event: session-end).
+EVENT="session-end"
+. "$(dirname "$0")/_post.sh"

package/hooks/user-prompt-submit.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Claude Code UserPromptSubmit hook → massa-ai observation (event: user-prompt).
+EVENT="user-prompt"
+. "$(dirname "$0")/_post.sh"