@agentuity/claude-code 1.0.5

package/hooks/scripts/session-end.sh

@@ -0,0 +1,203 @@
+#!/usr/bin/env bash
+# Session end hook: Save session context via TWO paths:
+#
+# PATH 1 (Immediate): Structured KV save — session metadata + conversation extract.
+#   Fast, reliable, always works. Extracts actual text content from transcript.
+#
+# PATH 2 (Async/Agentic): Spawn background `claude -p` with the plugin loaded.
+#   Delegates to the Memory agent for full agentic processing:
+#   entity extraction, corrections, Vector upsert, structured conclusions.
+#   Runs as a fire-and-forget background process.
+#
+# This dual approach ensures:
+# - Something is ALWAYS saved (Path 1, even if claude -p fails)
+# - Full agentic memory processing happens asynchronously (Path 2)
+#
+# Receives JSON on stdin with:
+#   - session_id: session identifier
+#   - transcript_path: path to conversation JSONL file
+#   - cwd: working directory
+#   - reason: why session ended
+#
+# Claude Code JSONL format notes:
+#   - Each line is a JSON object with top-level .type field
+#   - Types: "user", "assistant", "progress", "file-history-snapshot"
+#   - Text content: .message.content[] where item .type == "text" and text in .text
+#   - "progress" entries (subagent updates) can be very large (100KB+)
+#   - Filter by line size (< 5KB) before jq processing to avoid OOM/hangs
+
+set -uo pipefail
+
+INPUT=$(cat)
+
+if ! command -v agentuity &>/dev/null; then
+  exit 0
+fi
+
+# Derive plugin root from this script's location
+# Script is at: <plugin_root>/hooks/scripts/session-end.sh
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Extract fields from input JSON
+if command -v jq &>/dev/null; then
+  SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+  TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+  REASON=$(echo "$INPUT" | jq -r '.reason // empty' 2>/dev/null)
+  CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+else
+  SESSION_ID=$(echo "$INPUT" | grep -o '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+  TRANSCRIPT_PATH=$(echo "$INPUT" | grep -o '"transcript_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+  REASON=$(echo "$INPUT" | grep -o '"reason"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+  CWD=$(echo "$INPUT" | grep -o '"cwd"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+fi
+
+if [ -z "$SESSION_ID" ] || [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+GIT_REMOTE=$(git remote get-url origin 2>/dev/null || echo "unknown")
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# ─────────────────────────────────────────────────────
+# Extract conversation content from JSONL transcript
+# ─────────────────────────────────────────────────────
+# Key: filter lines < 5KB to skip huge "progress" entries that crash jq.
+# Only extract .message.content[] items with .type == "text"
+
+CONVERSATION=""
+if command -v jq &>/dev/null && command -v awk &>/dev/null; then
+  CONVERSATION=$(awk 'length < 5000' "$TRANSCRIPT_PATH" 2>/dev/null | jq -r '
+    if .type == "assistant" then
+      .message.content[]? | select(.type == "text") | "ASSISTANT: " + (.text // "")
+    elif .type == "user" then
+      .message.content[]? | select(.type == "text") | "USER: " + (.text // "")
+    else empty end
+  ' 2>/dev/null | tail -40 | head -c 8000)
+fi
+
+# Fallback: raw tail
+if [ -z "$CONVERSATION" ]; then
+  CONVERSATION=$(tail -20 "$TRANSCRIPT_PATH" 2>/dev/null | head -c 4000)
+fi
+
+# ─────────────────────────────────────────────────────
+# PATH 1: Immediate structured KV save
+# ─────────────────────────────────────────────────────
+
+SESSION_RECORD=$(jq -n \
+  --arg sid "$SESSION_ID" \
+  --arg branch "$GIT_BRANCH" \
+  --arg remote "$GIT_REMOTE" \
+  --arg reason "$REASON" \
+  --arg ts "$TIMESTAMP" \
+  --arg cwd "$CWD" \
+  --arg convo "$CONVERSATION" \
+  '{
+    sessionId: $sid,
+    branch: $branch,
+    remote: $remote,
+    endReason: $reason,
+    timestamp: $ts,
+    source: "claude-code",
+    cwd: $cwd,
+    conversation: $convo
+  }' 2>/dev/null)
+
+if [ -n "$SESSION_RECORD" ]; then
+  agentuity cloud kv set agentuity-opencode-memory "session:cc:${SESSION_ID}" "$SESSION_RECORD" --region use 2>/dev/null || true
+fi
+
+# ─────────────────────────────────────────────────────
+# PATH 2: Async agentic processing via background claude -p
+# ─────────────────────────────────────────────────────
+# Spawns a background claude -p with the plugin loaded, delegating to the
+# Memory agent for full agentic processing (entity extraction, corrections,
+# Vector upsert, structured conclusions).
+#
+# Key learnings from iteration:
+#   - --allowedTools must be SEPARATE arguments, not comma-separated
+#   - Pattern syntax is Bash(agentuity *) not Bash(pattern agentuity*)
+#   - Memory agent (via Task tool) handles all KV/Vector storage
+#   - --plugin-dir loads the plugin so Task can access the Memory agent
+#
+# This is "Option A" — local/sandbox use. For production at scale,
+# replace with queue-based worker (Option B) or control plane (Option C).
+
+if command -v claude &>/dev/null; then
+  # Write session context to temp file for claude -p to read
+  MEMORY_FILE=$(mktemp /tmp/agentuity-session-XXXXXX.md)
+
+  cat > "$MEMORY_FILE" <<MEMORY_CONTEXT
+# Session Memorialization Request
+
+**Session ID:** ${SESSION_ID}
+**Branch:** ${GIT_BRANCH}
+**Repository:** ${GIT_REMOTE}
+**Working Directory:** ${CWD}
+**End Reason:** ${REASON}
+**Timestamp:** ${TIMESTAMP}
+
+## Conversation Transcript
+
+${CONVERSATION}
+MEMORY_CONTEXT
+
+  LOG_DIR="/tmp/agentuity-memory-logs"
+  mkdir -p "$LOG_DIR" 2>/dev/null
+
+  # Spawn background claude -p with plugin loaded.
+  # Delegates to Memory agent via Task tool for full agentic processing.
+  # --dangerously-skip-permissions: background process, no user to prompt.
+  # --tools: restricts available tools to Task, Read, Bash (scoped).
+  nohup claude -p "Read the file ${MEMORY_FILE} which contains a session transcript to memorialize.
+
+Use the Task tool to delegate to the Memory agent:
+- subagent_type: agentuity-coder:agentuity-coder-memory
+- description: Memorialize session ${SESSION_ID}
+- prompt: Memorialize this session. You are being invoked automatically at session end. Read the file ${MEMORY_FILE} for the full session context. Then perform a full session memorialization: create a session summary (PROBLEM, CONTEXT, DECISIONS, CORRECTIONS, SOLUTIONS, PATTERNS, FILES, OPEN QUESTIONS), extract and store corrections to KV, store decisions to KV, upsert the full session document to Vector for semantic search, and apply reasoning to extract conclusions. Session ID: ${SESSION_ID}, Branch: ${GIT_BRANCH}, Repo: ${GIT_REMOTE}. Do NOT ask questions. Prioritize corrections and decisions.
+
+After the Memory agent completes, clean up by running: rm ${MEMORY_FILE}" \
+    --plugin-dir "$PLUGIN_ROOT" \
+    --dangerously-skip-permissions \
+    --tools "Task,Read,Bash" \
+    > "$LOG_DIR/session-${SESSION_ID}.log" 2>&1 &
+
+  # Don't wait for completion — fire and forget
+fi
+
+# ─────────────────────────────────────────────────────
+# (Future) PATH 3: Queue publish for worker-based processing
+# ─────────────────────────────────────────────────────
+# Uncomment when a queue worker (Option B/C) is available.
+# The queue provides durability, retry, and DLQ for production use.
+#
+# QUEUE_PAYLOAD=$(jq -n \
+#   --arg type "session-memorialize" \
+#   --arg sid "$SESSION_ID" \
+#   --arg branch "$GIT_BRANCH" \
+#   --arg remote "$GIT_REMOTE" \
+#   --arg cwd "$CWD" \
+#   --arg reason "$REASON" \
+#   --arg ts "$TIMESTAMP" \
+#   --arg convo "$CONVERSATION" \
+#   '{
+#     type: $type,
+#     sessionId: $sid,
+#     branch: $branch,
+#     remote: $remote,
+#     cwd: $cwd,
+#     endReason: $reason,
+#     timestamp: $ts,
+#     transcript: $convo
+#   }' 2>/dev/null)
+#
+# if [ -n "$QUEUE_PAYLOAD" ]; then
+#   agentuity cloud queue publish coder-memory-processing "$QUEUE_PAYLOAD" \
+#     --metadata "{\"sessionId\":\"$SESSION_ID\",\"branch\":\"$GIT_BRANCH\",\"type\":\"session-memorialize\"}" \
+#     --idempotency-key "session:$SESSION_ID" \
+#     2>/dev/null || true
+# fi
+
+exit 0

package/hooks/scripts/session-start.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Session start hook: Gather Agentuity context
+set -euo pipefail
+
+# Find agentuity.json by walking up directories
+find_agentuity_json() {
+  local dir="$PWD"
+  while [ "$dir" != "/" ]; do
+    if [ -f "$dir/agentuity.json" ]; then
+      echo "$dir/agentuity.json"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+# Initialize context
+CONTEXT="{}"
+
+# Check CLI availability
+if command -v agentuity &>/dev/null; then
+  CLI_AVAILABLE=true
+else
+  CLI_AVAILABLE=false
+fi
+
+# Read agentuity.json
+AGENTUITY_JSON=""
+if AGENTUITY_JSON_PATH=$(find_agentuity_json); then
+  AGENTUITY_JSON=$(cat "$AGENTUITY_JSON_PATH" 2>/dev/null || echo "{}")
+fi
+
+# Extract project info
+PROJECT_ID=$(echo "$AGENTUITY_JSON" | grep -o '"projectId"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"projectId"[[:space:]]*:[[:space:]]*"\([^"]*\)"/\1/' || echo "")
+ORG_ID=$(echo "$AGENTUITY_JSON" | grep -o '"orgId"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"orgId"[[:space:]]*:[[:space:]]*"\([^"]*\)"/\1/' || echo "")
+
+# If no orgId in agentuity.json, try CLI profile
+if [ -z "$ORG_ID" ] && [ -f "$HOME/.config/agentuity/production.yaml" ]; then
+  ORG_ID=$(grep 'orgId' "$HOME/.config/agentuity/production.yaml" 2>/dev/null | head -1 | sed 's/.*orgId:[[:space:]]*//' | tr -d '"' || echo "")
+fi
+
+# Get user info from CLI
+USER_INFO=""
+if [ "$CLI_AVAILABLE" = true ]; then
+  USER_INFO=$(agentuity auth whoami --json 2>/dev/null || echo "")
+fi
+
+# Get git info
+GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+GIT_REMOTE=$(git remote get-url origin 2>/dev/null || echo "unknown")
+
+# Output context
+cat <<EOF
+{
+  "agentuity": {
+    "cliAvailable": $CLI_AVAILABLE,
+    "projectId": "$PROJECT_ID",
+    "orgId": "$ORG_ID",
+    "configPath": "${AGENTUITY_JSON_PATH:-}",
+    "userInfo": ${USER_INFO:-null}
+  },
+  "git": {
+    "branch": "$GIT_BRANCH",
+    "remote": "$GIT_REMOTE"
+  }
+}
+EOF

package/hooks/scripts/setup-cadence.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# Setup script for Cadence mode.
+# Creates the .claude/agentuity-cadence.local.md state file and saves initial state to KV.
+#
+# Usage: setup-cadence.sh [--max-iterations N] [--completion-promise TEXT] PROMPT
+#
+# The state file is read by cadence-stop.sh (Stop hook) to keep
+# the loop running until the completion promise is detected.
+# State is also persisted to Agentuity Cloud KV for cross-session recall.
+
+set -euo pipefail
+
+MAX_ITERATIONS=50
+COMPLETION_PROMISE="DONE"
+PROMPT=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --max-iterations)
+      MAX_ITERATIONS="$2"
+      shift 2
+      ;;
+    --completion-promise)
+      COMPLETION_PROMISE="$2"
+      shift 2
+      ;;
+    -h|--help)
+      echo "Usage: setup-cadence.sh [OPTIONS] PROMPT"
+      echo ""
+      echo "Options:"
+      echo "  --max-iterations N        Maximum loop iterations (default: 50)"
+      echo "  --completion-promise TEXT  Completion signal text (default: DONE)"
+      echo "  -h, --help                Show this help"
+      exit 0
+      ;;
+    *)
+      # Everything else is the prompt
+      if [ -z "$PROMPT" ]; then
+        PROMPT="$1"
+      else
+        PROMPT="$PROMPT $1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [ -z "$PROMPT" ]; then
+  echo "Error: No prompt provided" >&2
+  echo "Usage: setup-cadence.sh [OPTIONS] PROMPT" >&2
+  exit 1
+fi
+
+# Validate max-iterations
+if ! [[ "$MAX_ITERATIONS" =~ ^[0-9]+$ ]] || [[ "$MAX_ITERATIONS" -lt 1 ]]; then
+  echo "Error: --max-iterations must be a positive integer" >&2
+  exit 1
+fi
+
+# Generate a loop ID: lp_{short_name}_{random}
+# Take first 3 words of prompt, lowercase, underscored, plus random suffix
+SHORT_NAME=$(echo "$PROMPT" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '_' | cut -c1-30 | sed 's/_$//')
+RANDOM_SUFFIX=$(head -c 4 /dev/urandom | od -An -tx1 | tr -d ' \n' | cut -c1-6)
+LOOP_ID="lp_${SHORT_NAME}_${RANDOM_SUFFIX}"
+
+# Get git branch
+GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+
+# Create .claude directory if needed
+mkdir -p .claude
+
+# Check for existing cadence session
+if [ -f ".claude/agentuity-cadence.local.md" ]; then
+  EXISTING_ITER=$(sed -n '/^---$/,/^---$/{ /^iteration:/s/iteration: *//p }' .claude/agentuity-cadence.local.md)
+  EXISTING_LOOP=$(sed -n '/^---$/,/^---$/{ /^loop_id:/s/loop_id: *//p }' .claude/agentuity-cadence.local.md | tr -d '"')
+  echo "Warning: Active Cadence loop found (${EXISTING_LOOP:-?} at iteration ${EXISTING_ITER:-?}). Replacing with new loop." >&2
+  rm -f .claude/agentuity-cadence.local.md
+fi
+
+# Create state file
+CREATED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+cat > .claude/agentuity-cadence.local.md << STATEFILE
+---
+active: true
+loop_id: "${LOOP_ID}"
+iteration: 1
+max_iterations: ${MAX_ITERATIONS}
+completion_promise: "${COMPLETION_PROMISE}"
+branch: "${GIT_BRANCH}"
+created_at: ${CREATED_AT}
+---
+
+${PROMPT}
+STATEFILE
+
+# Save initial cadence state to KV (if agentuity CLI available)
+if command -v agentuity &>/dev/null; then
+  KV_STATE=$(jq -n \
+    --arg loopId "$LOOP_ID" \
+    --arg prompt "$PROMPT" \
+    --arg branch "$GIT_BRANCH" \
+    --arg createdAt "$CREATED_AT" \
+    --argjson iteration 1 \
+    --argjson maxIterations "$MAX_ITERATIONS" \
+    --arg completionPromise "$COMPLETION_PROMISE" \
+    --arg status "active" \
+    '{
+      loopId: $loopId,
+      prompt: $prompt,
+      branch: $branch,
+      iteration: $iteration,
+      maxIterations: $maxIterations,
+      completionPromise: $completionPromise,
+      status: $status,
+      startedAt: $createdAt,
+      lastActivity: $createdAt,
+      checkpoints: []
+    }')
+  agentuity cloud kv set agentuity-opencode-memory "cadence:${LOOP_ID}" "$KV_STATE" --region use 2>/dev/null || true
+fi
+
+echo "Cadence loop initialized:"
+echo "  Loop ID: ${LOOP_ID}"
+echo "  Max iterations: ${MAX_ITERATIONS}"
+echo "  Completion promise: ${COMPLETION_PROMISE}"
+echo "  Branch: ${GIT_BRANCH}"
+echo "  State file: .claude/agentuity-cadence.local.md"
+echo "  KV key: cadence:${LOOP_ID}"
+echo ""
+echo "The loop will continue until you output <promise>${COMPLETION_PROMISE}</promise>"
+echo "or reach ${MAX_ITERATIONS} iterations."
+echo "To cancel: /agentuity-cadence-cancel"

package/hooks/scripts/stop-memory-save.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Stop hook: Request memory save before session ends (interactive mode only).
+#
+# In INTERACTIVE mode: blocks the first stop to request memory save via Memory agent.
+# In HEADLESS mode (-p): skips entirely — session-end.sh handles KV save directly.
+#
+# Exit 0 = let Claude stop normally.
+# Exit 2 + JSON with decision:block = prevent stop and inject instructions.
+
+INPUT=$(cat)
+
+# Check if agentuity CLI is available — if not, skip memory save
+if ! command -v agentuity &>/dev/null; then
+  exit 0
+fi
+
+# If Cadence mode is active, skip memory save — cadence-stop.sh handles the loop
+# and includes Memory checkpoints at each iteration.
+if [ -f ".claude/agentuity-cadence.local.md" ]; then
+  exit 0
+fi
+
+# Detect headless mode: check if CLAUDE_CODE_HEADLESS is set, or if
+# the session was started with -p (no TTY on parent's stdin).
+# In headless mode, session-end.sh handles memory save directly via KV.
+if [ "${CLAUDE_CODE_HEADLESS:-}" = "1" ] || [ "${CLAUDE_NON_INTERACTIVE:-}" = "1" ]; then
+  exit 0
+fi
+
+# Also detect headless by checking if the parent process has no TTY
+if ! kill -0 $PPID 2>/dev/null || [ ! -t 0 ] 2>/dev/null; then
+  # Can't reliably detect, but hooks don't have a TTY in either mode.
+  # Use the marker-only approach and keep the block minimal.
+  :
+fi
+
+# Use a session-specific marker file to track save state.
+# PPID is the Claude Code process that spawns hooks — consistent within a session.
+MARKER_DIR="/tmp/agentuity-coder-memory"
+mkdir -p "$MARKER_DIR" 2>/dev/null
+MARKER_FILE="$MARKER_DIR/saved-$PPID"
+
+# If we've already requested a save this session, let Claude stop
+if [ -f "$MARKER_FILE" ]; then
+  exit 0
+fi
+
+# Mark that we've requested a save
+touch "$MARKER_FILE"
+
+# Clean up old markers (older than 24h)
+find "$MARKER_DIR" -name 'saved-*' -mtime +1 -delete 2>/dev/null || true
+
+# Get git branch for context
+GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+
+# Block the stop and request agentic memory save via Memory agent.
+# The Memory agent has full reasoning capabilities: entity extraction,
+# corrections identification, Vector upsert, and structured KV storage.
+#
+# IMPORTANT: We use the Task tool to delegate to Memory agent (subagent),
+# NOT Lead, to avoid complex multi-agent orchestration that can hang.
+cat <<EOF
+{
+  "decision": "block",
+  "reason": "Before ending this session, you MUST save session context to persistent memory. Use the Task tool to delegate to the Memory agent:\n\nTask tool parameters:\n- subagent_type: agentuity-coder:agentuity-coder-memory\n- description: Save session memory\n- prompt: \"Memorialize this session. You are being invoked automatically at session end. Review the conversation above and perform a full session memorialization:\\n\\n1. Create a session summary using the Session Summary Template (PROBLEM, CONTEXT, DECISIONS, CORRECTIONS, SOLUTIONS, PATTERNS, FILES, OPEN QUESTIONS)\\n2. Extract and store any corrections/mistakes as high-priority KV entries (correction:{name})\\n3. Store any key decisions (decision:{name})\\n4. Store any reusable patterns (pattern:{name})\\n5. Upsert the FULL session document to Vector storage for semantic search\\n6. Apply reasoning to extract conclusions (explicit, deductive, inductive, abductive) and update entity representations\\n7. Current branch: ${GIT_BRANCH}\\n\\nDo NOT ask questions. Summarize and store everything you can from the conversation history. Prioritize corrections and decisions.\"\n\nAfter the Memory agent completes, you may stop."
+}
+EOF
+exit 2

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@agentuity/claude-code",
+	"version": "1.0.5",
+	"license": "Apache-2.0",
+	"author": "Agentuity employees and contributors",
+	"description": "Agentuity Coder plugin for Claude Code with specialized AI coding agents",
+	"type": "module",
+	"main": "./dist/install.js",
+	"module": "./dist/install.js",
+	"types": "./dist/install.d.ts",
+	"files": [
+		"AGENTS.md",
+		"README.md",
+		"LICENSE",
+		".claude-plugin",
+		"agents",
+		"skills",
+		"hooks",
+		"commands",
+		"src",
+		"dist"
+	],
+	"exports": {
+		".": "./dist/install.js"
+	},
+	"typesVersions": {
+		"*": {
+			".": [
+				"./dist/install.d.ts"
+			]
+		}
+	},
+	"scripts": {
+		"clean": "rm -rf dist tsconfig.tsbuildinfo",
+		"build": "bunx tsc --build --force",
+		"typecheck": "bunx tsc --noEmit",
+		"test": "bun test",
+		"prepublishOnly": "bun run clean && bun run build"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"bun-types": "latest",
+		"typescript": "^5.9.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"sideEffects": false
+}