@tekmidian/pai 0.3.1 → 0.4.0

package/scripts/build-hooks.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Build TypeScript hooks into standalone .mjs files using esbuild.
+ *
+ * Each hook is fully self-contained — lib/ dependencies are inlined.
+ * Output: dist/hooks/<name>.mjs with #!/usr/bin/env node shebang.
+ */
+
+import { buildSync } from "esbuild";
+import { readdirSync, statSync, chmodSync } from "fs";
+import { join, relative, basename } from "path";
+
+const HOOKS_SRC = "src/hooks/ts";
+const HOOKS_OUT = "dist/hooks";
+
+// Collect all .ts entry points (skip lib/ — those are bundled into each hook)
+function collectEntryPoints(dir) {
+  const entries = [];
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    if (name === "lib") continue;
+    if (statSync(full).isDirectory()) {
+      entries.push(...collectEntryPoints(full));
+    } else if (name.endsWith(".ts")) {
+      entries.push(full);
+    }
+  }
+  return entries;
+}
+
+const entryPoints = collectEntryPoints(HOOKS_SRC);
+
+console.log(`Building ${entryPoints.length} hooks with esbuild...`);
+
+for (const entry of entryPoints) {
+  const outfile = join(HOOKS_OUT, basename(entry).replace(/\.ts$/, ".mjs"));
+
+  buildSync({
+    entryPoints: [entry],
+    bundle: true,
+    platform: "node",
+    target: "node20",
+    format: "esm",
+    outfile,
+    sourcemap: true,
+  });
+
+  chmodSync(outfile, 0o755);
+}
+
+console.log(`✔ ${entryPoints.length} hooks built to ${HOOKS_OUT}/`);

package/src/hooks/pre-compact.sh

@@ -8,6 +8,10 @@
 
 PAI_OS="pai"
 
+# Set tab color to working state while compacting
+TAB_COLOR="${PAI_DIR:-$HOME/.claude}/tab-color-command.sh"
+[[ -x "$TAB_COLOR" ]] && "$TAB_COLOR" working
+
 # Bail gracefully if pai is not installed
 command -v "$PAI_OS" &>/dev/null || exit 0
 command -v sqlite3 &>/dev/null || exit 0

package/src/hooks/session-stop.sh

@@ -90,4 +90,8 @@ fi
 
 "$PAI_OS" session handover "$PROJECT_SLUG" latest 2>/dev/null || true
 
+# Set tab color to completed state when session ends
+TAB_COLOR="${PAI_DIR:-$HOME/.claude}/tab-color-command.sh"
+[[ -x "$TAB_COLOR" ]] && "$TAB_COLOR" completed
+
 exit 0

package/src/hooks/ts/capture-all-events.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * Capture All Events Hook
+ * Captures ALL Claude Code hook events (not just tools) to JSONL
+ * This replaces the Python send_event.py hook
+ * Enhanced with agent instance metadata extraction
+ */
+
+import { readFileSync, appendFileSync, mkdirSync, existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { PAI_DIR, HISTORY_DIR } from './lib/pai-paths';
+import { enrichEventWithAgentMetadata, isAgentSpawningCall } from './lib/metadata-extraction';
+
+interface HookEvent {
+  source_app: string;
+  session_id: string;
+  hook_event_type: string;
+  payload: Record<string, any>;
+  timestamp: number;
+  timestamp_local: string;
+}
+
+// Get local timestamp using system timezone
+function getLocalTimestamp(): string {
+  const date = new Date();
+  const tz = process.env.TIME_ZONE || Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const localDate = new Date(date.toLocaleString('en-US', { timeZone: tz }));
+
+  const year = localDate.getFullYear();
+  const month = String(localDate.getMonth() + 1).padStart(2, '0');
+  const day = String(localDate.getDate()).padStart(2, '0');
+  const hours = String(localDate.getHours()).padStart(2, '0');
+  const minutes = String(localDate.getMinutes()).padStart(2, '0');
+  const seconds = String(localDate.getSeconds()).padStart(2, '0');
+
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds} ${tz}`;
+}
+
+// Get current events file path
+function getEventsFilePath(): string {
+  const now = new Date();
+  const tz = process.env.TIME_ZONE || Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const localDate = new Date(now.toLocaleString('en-US', { timeZone: tz }));
+  const year = localDate.getFullYear();
+  const month = String(localDate.getMonth() + 1).padStart(2, '0');
+  const day = String(localDate.getDate()).padStart(2, '0');
+
+  const monthDir = join(HISTORY_DIR, 'raw-outputs', `${year}-${month}`);
+
+  // Ensure directory exists
+  if (!existsSync(monthDir)) {
+    mkdirSync(monthDir, { recursive: true });
+  }
+
+  return join(monthDir, `${year}-${month}-${day}_all-events.jsonl`);
+}
+
+// Session-to-agent mapping functions
+function getSessionMappingFile(): string {
+  return join(PAI_DIR, 'agent-sessions.json');
+}
+
+function getAgentForSession(sessionId: string): string {
+  try {
+    const mappingFile = getSessionMappingFile();
+    if (existsSync(mappingFile)) {
+      const mappings = JSON.parse(readFileSync(mappingFile, 'utf-8'));
+      return mappings[sessionId] || 'pai';
+    }
+  } catch (error) {
+    // Ignore errors, default to pai
+  }
+  return 'pai';
+}
+
+function setAgentForSession(sessionId: string, agentName: string): void {
+  try {
+    const mappingFile = getSessionMappingFile();
+    let mappings: Record<string, string> = {};
+
+    if (existsSync(mappingFile)) {
+      mappings = JSON.parse(readFileSync(mappingFile, 'utf-8'));
+    }
+
+    mappings[sessionId] = agentName;
+    writeFileSync(mappingFile, JSON.stringify(mappings, null, 2), 'utf-8');
+  } catch (error) {
+    // Silently fail - don't block
+  }
+}
+
+async function main() {
+  try {
+    // Get event type from command line args
+    const args = process.argv.slice(2);
+    const eventTypeIndex = args.indexOf('--event-type');
+
+    if (eventTypeIndex === -1) {
+      console.error('Missing --event-type argument');
+      process.exit(0); // Don't block Claude Code
+    }
+
+    const eventType = args[eventTypeIndex + 1];
+
+    // Read hook data from stdin
+    const chunks: Buffer[] = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    const stdinData = Buffer.concat(chunks).toString('utf-8');
+    const hookData = JSON.parse(stdinData);
+
+    // Detect agent type from session mapping or payload
+    const sessionId = hookData.session_id || 'main';
+    let agentName = getAgentForSession(sessionId);
+
+    // If this is a Task tool launching a subagent, update the session mapping
+    if (hookData.tool_name === 'Task' && hookData.tool_input?.subagent_type) {
+      agentName = hookData.tool_input.subagent_type;
+      setAgentForSession(sessionId, agentName);
+    }
+    // If this is a SubagentStop or Stop event, reset to pai
+    else if (eventType === 'SubagentStop' || eventType === 'Stop') {
+      agentName = 'pai';
+      setAgentForSession(sessionId, 'pai');
+    }
+    // Check if CLAUDE_CODE_AGENT env variable is set (for subagents)
+    else if (process.env.CLAUDE_CODE_AGENT) {
+      agentName = process.env.CLAUDE_CODE_AGENT;
+      setAgentForSession(sessionId, agentName);
+    }
+    // Check if agent type is in the payload (alternative detection method)
+    else if (hookData.agent_type) {
+      agentName = hookData.agent_type;
+      setAgentForSession(sessionId, agentName);
+    }
+    // Check if this is from a subagent based on cwd containing 'agent'
+    else if (hookData.cwd && hookData.cwd.includes('/agents/')) {
+      // Extract agent name from path like "/agents/designer/"
+      const agentMatch = hookData.cwd.match(/\/agents\/([^\/]+)/);
+      if (agentMatch) {
+        agentName = agentMatch[1];
+        setAgentForSession(sessionId, agentName);
+      }
+    }
+
+    // Create base event object
+    let event: HookEvent = {
+      source_app: agentName,
+      session_id: hookData.session_id || 'main',
+      hook_event_type: eventType,
+      payload: hookData,
+      timestamp: Date.now(),
+      timestamp_local: getLocalTimestamp()
+    };
+
+    // Enrich with agent instance metadata if this is a Task tool call
+    if (isAgentSpawningCall(hookData.tool_name, hookData.tool_input)) {
+      event = enrichEventWithAgentMetadata(
+        event,
+        hookData.tool_input,
+        hookData.description
+      );
+    }
+
+    // Append to events file
+    const eventsFile = getEventsFilePath();
+    const jsonLine = JSON.stringify(event) + '\n';
+    appendFileSync(eventsFile, jsonLine, 'utf-8');
+
+  } catch (error) {
+    // Silently fail - don't block Claude Code
+    console.error('Event capture error:', error);
+  }
+
+  process.exit(0);
+}
+
+main();

package/src/hooks/ts/lib/detect-environment.ts

@@ -0,0 +1,53 @@
+/**
+ * detect-environment.ts
+ *
+ * Environment detection utilities for PAI hooks.
+ *
+ * Determines if the system is running in a remote environment (SSH, cloud, etc.)
+ * to conditionally adjust hook behaviour.
+ *
+ * Detection Logic (in priority order):
+ * 1. Check PAI_ENVIRONMENT env var (explicit override)
+ * 2. Check for SSH indicators (SSH_CLIENT, SSH_TTY)
+ * 3. Default to local environment
+ */
+
+/**
+ * Check if we're running in an SSH session
+ * Looks for SSH_CLIENT or SSH_TTY environment variables
+ */
+function isSSHSession(): boolean {
+  return !!(process.env.SSH_CLIENT || process.env.SSH_TTY);
+}
+
+/**
+ * Main detection function - determines if we're in a remote environment
+ *
+ * Returns:
+ * - true: Remote environment
+ * - false: Local environment
+ *
+ * Detection priority:
+ * 1. PAI_ENVIRONMENT === 'remote' → true
+ * 2. PAI_ENVIRONMENT === 'local' → false
+ * 3. SSH_CLIENT or SSH_TTY set → true
+ * 4. Otherwise → false (local)
+ */
+export function isRemoteEnvironment(): boolean {
+  // 1. Check explicit environment override
+  const paiEnv = process.env.PAI_ENVIRONMENT?.toLowerCase();
+  if (paiEnv === 'remote') {
+    return true;
+  }
+  if (paiEnv === 'local') {
+    return false;
+  }
+
+  // 2. Check for SSH session
+  if (isSSHSession()) {
+    return true;
+  }
+
+  // 3. Default to local environment
+  return false;
+}

package/src/hooks/ts/lib/metadata-extraction.ts

@@ -0,0 +1,144 @@
+/**
+ * Metadata Extraction Library for UOCS Enhancement
+ *
+ * Extracts agent instance IDs, parent-child relationships, and session info
+ * from Task tool calls and other tool inputs.
+ *
+ * Design Philosophy: Optional extraction with graceful fallbacks
+ * - If instance IDs are present in descriptions/prompts, extract them
+ * - If not present, fall back to agent type only
+ * - Never fail - always return usable metadata
+ */
+
+export interface AgentInstanceMetadata {
+  agent_instance_id?: string;      // "perplexity-researcher-1" (full ID)
+  agent_type?: string;              // "perplexity-researcher" (base type)
+  instance_number?: number;         // 1 (sequence number)
+  parent_session_id?: string;       // Session that spawned this agent
+  parent_task_id?: string;          // Task ID that spawned this agent
+}
+
+/**
+ * Extract agent instance ID from Task tool input
+ *
+ * Looks for patterns in priority order:
+ * 1. [agent-type-N] in description (e.g., "Research topic [perplexity-researcher-1]")
+ * 2. [AGENT_INSTANCE: agent-type-N] in prompt
+ * 3. subagent_type field (fallback to just type, no instance number)
+ *
+ * @param toolInput The tool input object from PreToolUse/PostToolUse hooks
+ * @param description Optional description field from tool input
+ * @returns Metadata object with extracted information
+ */
+export function extractAgentInstanceId(
+  toolInput: any,
+  description?: string
+): AgentInstanceMetadata {
+  const result: AgentInstanceMetadata = {};
+
+  // Strategy 1: Extract from description [agent-type-N]
+  // Example: "Research consumer complaints [perplexity-researcher-1]"
+  if (description) {
+    const descMatch = description.match(/\[([a-z-]+-researcher)-(\d+)\]/);
+    if (descMatch) {
+      result.agent_type = descMatch[1];
+      result.instance_number = parseInt(descMatch[2], 10);
+      result.agent_instance_id = `${result.agent_type}-${result.instance_number}`;
+    }
+  }
+
+  // Strategy 2: Extract from prompt [AGENT_INSTANCE: ...]
+  // Example: "[AGENT_INSTANCE: perplexity-researcher-1]"
+  if (!result.agent_instance_id && toolInput?.prompt && typeof toolInput.prompt === 'string') {
+    const promptMatch = toolInput.prompt.match(/\[AGENT_INSTANCE:\s*([^\]]+)\]/);
+    if (promptMatch) {
+      result.agent_instance_id = promptMatch[1].trim();
+
+      // Parse agent type and instance number from ID
+      const parts = result.agent_instance_id.match(/^([a-z-]+)-(\d+)$/);
+      if (parts) {
+        result.agent_type = parts[1];
+        result.instance_number = parseInt(parts[2], 10);
+      }
+    }
+  }
+
+  // Strategy 3: Extract parent session from prompt
+  // Example: "[PARENT_SESSION: b7062b5a-03d3-4168-9555-a748e0b2efa3]"
+  if (toolInput?.prompt && typeof toolInput.prompt === 'string') {
+    const parentSessionMatch = toolInput.prompt.match(/\[PARENT_SESSION:\s*([^\]]+)\]/);
+    if (parentSessionMatch) {
+      result.parent_session_id = parentSessionMatch[1].trim();
+    }
+
+    // Extract parent task from prompt
+    // Example: "[PARENT_TASK: research_1731445892345]"
+    const parentTaskMatch = toolInput.prompt.match(/\[PARENT_TASK:\s*([^\]]+)\]/);
+    if (parentTaskMatch) {
+      result.parent_task_id = parentTaskMatch[1].trim();
+    }
+  }
+
+  // Strategy 4: Fallback to subagent_type if available (no instance number)
+  // This ensures we at least capture the agent type even without instance IDs
+  if (!result.agent_type && toolInput?.subagent_type) {
+    result.agent_type = toolInput.subagent_type;
+  }
+
+  return result;
+}
+
+/**
+ * Enrich event with agent metadata
+ *
+ * Takes a base event object and adds agent instance metadata to it.
+ * Returns a new object with merged metadata.
+ *
+ * @param event Base event object (from PreToolUse/PostToolUse)
+ * @param toolInput Tool input object
+ * @param description Optional description field
+ * @returns Enriched event with agent metadata
+ */
+export function enrichEventWithAgentMetadata(
+  event: any,
+  toolInput: any,
+  description?: string
+): any {
+  const metadata = extractAgentInstanceId(toolInput, description);
+
+  // Only add fields that have values (keep events clean)
+  const enrichedEvent = { ...event };
+
+  if (metadata.agent_instance_id) {
+    enrichedEvent.agent_instance_id = metadata.agent_instance_id;
+  }
+
+  if (metadata.agent_type) {
+    enrichedEvent.agent_type = metadata.agent_type;
+  }
+
+  if (metadata.instance_number !== undefined) {
+    enrichedEvent.instance_number = metadata.instance_number;
+  }
+
+  if (metadata.parent_session_id) {
+    enrichedEvent.parent_session_id = metadata.parent_session_id;
+  }
+
+  if (metadata.parent_task_id) {
+    enrichedEvent.parent_task_id = metadata.parent_task_id;
+  }
+
+  return enrichedEvent;
+}
+
+/**
+ * Check if a tool call is spawning a subagent
+ *
+ * @param toolName Name of the tool being called
+ * @param toolInput Tool input object
+ * @returns true if this is a Task tool call spawning an agent
+ */
+export function isAgentSpawningCall(toolName: string, toolInput: any): boolean {
+  return toolName === 'Task' && toolInput?.subagent_type !== undefined;
+}

package/src/hooks/ts/lib/pai-paths.ts

@@ -0,0 +1,124 @@
+/**
+ * PAI Path Resolution - Single Source of Truth
+ *
+ * This module provides consistent path resolution across all PAI hooks.
+ * It handles PAI_DIR detection whether set explicitly or defaulting to ~/.claude
+ *
+ * ALSO loads .env file from PAI_DIR so all hooks get environment variables
+ * without relying on Claude Code's settings.json injection.
+ *
+ * Usage in hooks:
+ *   import { PAI_DIR, HOOKS_DIR, SKILLS_DIR } from './lib/pai-paths';
+ */
+
+import { homedir } from 'os';
+import { resolve, join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+
+/**
+ * Load .env file and inject into process.env
+ * Must run BEFORE PAI_DIR resolution so .env can set PAI_DIR if needed
+ */
+function loadEnvFile(): void {
+  // Check common locations for .env
+  const possiblePaths = [
+    resolve(process.env.PAI_DIR || '', '.env'),
+    resolve(homedir(), '.claude', '.env'),
+  ];
+
+  for (const envPath of possiblePaths) {
+    if (existsSync(envPath)) {
+      try {
+        const content = readFileSync(envPath, 'utf-8');
+        for (const line of content.split('\n')) {
+          const trimmed = line.trim();
+          // Skip comments and empty lines
+          if (!trimmed || trimmed.startsWith('#')) continue;
+
+          const eqIndex = trimmed.indexOf('=');
+          if (eqIndex > 0) {
+            const key = trimmed.substring(0, eqIndex).trim();
+            let value = trimmed.substring(eqIndex + 1).trim();
+
+            // Remove surrounding quotes if present
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+              value = value.slice(1, -1);
+            }
+
+            // Expand $HOME and ~ in values
+            value = value.replace(/\$HOME/g, homedir());
+            value = value.replace(/^~(?=\/|$)/, homedir());
+
+            // Only set if not already defined (env vars take precedence)
+            if (process.env[key] === undefined) {
+              process.env[key] = value;
+            }
+          }
+        }
+        // Found and loaded, don't check other paths
+        break;
+      } catch {
+        // Silently continue if .env can't be read
+      }
+    }
+  }
+}
+
+// Load .env FIRST, before any other initialization
+loadEnvFile();
+
+/**
+ * Smart PAI_DIR detection with fallback
+ * Priority:
+ * 1. PAI_DIR environment variable (if set)
+ * 2. ~/.claude (standard location)
+ */
+export const PAI_DIR = process.env.PAI_DIR
+  ? resolve(process.env.PAI_DIR)
+  : resolve(homedir(), '.claude');
+
+/**
+ * Common PAI directories
+ */
+export const HOOKS_DIR = join(PAI_DIR, 'Hooks');
+export const SKILLS_DIR = join(PAI_DIR, 'Skills');
+export const AGENTS_DIR = join(PAI_DIR, 'Agents');
+export const HISTORY_DIR = join(PAI_DIR, 'History');
+export const COMMANDS_DIR = join(PAI_DIR, 'Commands');
+
+/**
+ * Validate PAI directory structure on first import
+ * This fails fast with a clear error if PAI is misconfigured
+ */
+function validatePAIStructure(): void {
+  if (!existsSync(PAI_DIR)) {
+    console.error(`PAI_DIR does not exist: ${PAI_DIR}`);
+    console.error(`   Expected ~/.claude or set PAI_DIR environment variable`);
+    process.exit(1);
+  }
+
+  if (!existsSync(HOOKS_DIR)) {
+    console.error(`PAI hooks directory not found: ${HOOKS_DIR}`);
+    console.error(`   Your PAI_DIR may be misconfigured`);
+    console.error(`   Current PAI_DIR: ${PAI_DIR}`);
+    process.exit(1);
+  }
+}
+
+// Run validation on module import
+// This ensures any hook that imports this module will fail fast if paths are wrong
+validatePAIStructure();
+
+/**
+ * Helper to get history file path with date-based organization
+ */
+export function getHistoryFilePath(subdir: string, filename: string): string {
+  const now = new Date();
+  const tz = process.env.TIME_ZONE || Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const localDate = new Date(now.toLocaleString('en-US', { timeZone: tz }));
+  const year = localDate.getFullYear();
+  const month = String(localDate.getMonth() + 1).padStart(2, '0');
+
+  return join(HISTORY_DIR, subdir, `${year}-${month}`, filename);
+}