feat: add internal hooks system

src/hooks/bundled/README.md

@@ -0,0 +1,186 @@
+# Bundled Internal Hooks
+
+This directory contains internal hooks that ship with Clawdbot. These hooks are automatically discovered and can be enabled/disabled via CLI or configuration.
+
+## Available Hooks
+
+### 💾 session-memory
+
+Automatically saves session context to memory when you issue `/new`.
+
+**Events**: `command:new`
+**What it does**: Creates a dated memory file with LLM-generated slug based on conversation content.
+**Output**: `<workspace>/memory/YYYY-MM-DD-slug.md` (defaults to `~/clawd`)
+
+**Enable**:
+```bash
+clawdbot hooks internal enable session-memory
+```
+
+### 📝 command-logger
+
+Logs all command events to a centralized audit file.
+
+**Events**: `command` (all commands)
+**What it does**: Appends JSONL entries to command log file.
+**Output**: `~/.clawdbot/logs/commands.log`
+
+**Enable**:
+```bash
+clawdbot hooks internal enable command-logger
+```
+
+## Hook Structure
+
+Each hook is a directory containing:
+
+- **HOOK.md**: Metadata and documentation in YAML frontmatter + Markdown
+- **handler.ts**: The hook handler function (default export)
+
+Example structure:
+```
+session-memory/
+├── HOOK.md          # Metadata + docs
+└── handler.ts       # Handler implementation
+```
+
+## HOOK.md Format
+
+```yaml
+---
+name: my-hook
+description: "Short description"
+homepage: https://docs.clawd.bot/hooks/my-hook
+metadata: {"clawdbot":{"emoji":"🔗","events":["command:new"],"requires":{"bins":["node"]}}}
+---
+
+# Hook Title
+
+Documentation goes here...
+```
+
+### Metadata Fields
+
+- **emoji**: Display emoji for CLI
+- **events**: Array of events to listen for (e.g., `["command:new", "session:start"]`)
+- **requires**: Optional requirements
+  - **bins**: Required binaries on PATH
+  - **anyBins**: At least one of these binaries must be present
+  - **env**: Required environment variables
+  - **config**: Required config paths (e.g., `["workspace.dir"]`)
+  - **os**: Required platforms (e.g., `["darwin", "linux"]`)
+- **install**: Installation methods (for bundled hooks: `[{"id":"bundled","kind":"bundled"}]`)
+
+## Creating Custom Hooks
+
+To create your own hooks, place them in:
+
+- **Workspace hooks**: `<workspace>/hooks/` (highest precedence)
+- **Managed hooks**: `~/.clawdbot/hooks/` (shared across workspaces)
+
+Custom hooks follow the same structure as bundled hooks.
+
+## Managing Hooks
+
+List all hooks:
+```bash
+clawdbot hooks internal list
+```
+
+Show hook details:
+```bash
+clawdbot hooks internal info session-memory
+```
+
+Check hook status:
+```bash
+clawdbot hooks internal check
+```
+
+Enable/disable:
+```bash
+clawdbot hooks internal enable session-memory
+clawdbot hooks internal disable command-logger
+```
+
+## Configuration
+
+Hooks can be configured in `~/.clawdbot/clawdbot.json`:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "enabled": true,
+      "entries": {
+        "session-memory": {
+          "enabled": true
+        },
+        "command-logger": {
+          "enabled": false
+        }
+      }
+    }
+  }
+}
+```
+
+## Event Types
+
+Currently supported events:
+
+- **command**: All command events
+- **command:new**: `/new` command specifically
+- **command:reset**: `/reset` command
+- **command:stop**: `/stop` command
+
+More event types coming soon (session lifecycle, agent errors, etc.).
+
+## Handler API
+
+Hook handlers receive an `InternalHookEvent` object:
+
+```typescript
+interface InternalHookEvent {
+  type: 'command' | 'session' | 'agent';
+  action: string;              // e.g., 'new', 'reset', 'stop'
+  sessionKey: string;
+  context: Record<string, unknown>;
+  timestamp: Date;
+  messages: string[];          // Push messages here to send to user
+}
+```
+
+Example handler:
+
+```typescript
+import type { InternalHookHandler } from '../../src/hooks/internal-hooks.js';
+
+const myHandler: InternalHookHandler = async (event) => {
+  if (event.type !== 'command' || event.action !== 'new') {
+    return;
+  }
+
+  // Your logic here
+  console.log('New command triggered!');
+
+  // Optionally send message to user
+  event.messages.push('✨ Hook executed!');
+};
+
+export default myHandler;
+```
+
+## Testing
+
+Test your hooks by:
+
+1. Place hook in workspace hooks directory
+2. Restart gateway: `pkill -9 -f 'clawdbot.*gateway' && pnpm clawdbot gateway`
+3. Enable the hook: `clawdbot hooks internal enable my-hook`
+4. Trigger the event (e.g., send `/new` command)
+5. Check gateway logs for hook execution
+
+## Documentation
+
+Full documentation: https://docs.clawd.bot/internal-hooks

src/hooks/bundled/command-logger/HOOK.md

@@ -0,0 +1,109 @@
+---
+name: command-logger
+description: "Log all command events to a centralized audit file"
+homepage: https://docs.clawd.bot/internal-hooks#command-logger
+metadata: {"clawdbot":{"emoji":"📝","events":["command"],"install":[{"id":"bundled","kind":"bundled","label":"Bundled with Clawdbot"}]}}
+---
+
+# Command Logger Hook
+
+Logs all command events (`/new`, `/reset`, `/stop`, etc.) to a centralized audit log file for debugging and monitoring purposes.
+
+## What It Does
+
+Every time you issue a command to the agent:
+
+1. **Captures event details** - Command action, timestamp, session key, sender ID, source
+2. **Appends to log file** - Writes a JSON line to `~/.clawdbot/logs/commands.log`
+3. **Silent operation** - Runs in the background without user notifications
+
+## Output Format
+
+Log entries are written in JSONL (JSON Lines) format:
+
+```json
+{"timestamp":"2026-01-16T14:30:00.000Z","action":"new","sessionKey":"agent:main:main","senderId":"+1234567890","source":"telegram"}
+{"timestamp":"2026-01-16T15:45:22.000Z","action":"stop","sessionKey":"agent:main:main","senderId":"user@example.com","source":"whatsapp"}
+```
+
+## Use Cases
+
+- **Debugging**: Track when commands were issued and from which source
+- **Auditing**: Monitor command usage across different channels
+- **Analytics**: Analyze command patterns and frequency
+- **Troubleshooting**: Investigate issues by reviewing command history
+
+## Log File Location
+
+`~/.clawdbot/logs/commands.log`
+
+## Requirements
+
+No requirements - this hook works out of the box on all platforms.
+
+## Configuration
+
+No configuration needed. The hook automatically:
+- Creates the log directory if it doesn't exist
+- Appends to the log file (doesn't overwrite)
+- Handles errors silently without disrupting command execution
+
+## Disabling
+
+To disable this hook:
+
+```bash
+clawdbot hooks internal disable command-logger
+```
+
+Or via config:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "command-logger": { "enabled": false }
+      }
+    }
+  }
+}
+```
+
+## Log Rotation
+
+The hook does not automatically rotate logs. To manage log size, you can:
+
+1. **Manual rotation**:
+   ```bash
+   mv ~/.clawdbot/logs/commands.log ~/.clawdbot/logs/commands.log.old
+   ```
+
+2. **Use logrotate** (Linux):
+   Create `/etc/logrotate.d/clawdbot`:
+   ```
+   /home/username/.clawdbot/logs/commands.log {
+       weekly
+       rotate 4
+       compress
+       missingok
+       notifempty
+   }
+   ```
+
+## Viewing Logs
+
+View recent commands:
+```bash
+tail -n 20 ~/.clawdbot/logs/commands.log
+```
+
+Pretty-print with jq:
+```bash
+cat ~/.clawdbot/logs/commands.log | jq .
+```
+
+Filter by action:
+```bash
+grep '"action":"new"' ~/.clawdbot/logs/commands.log | jq .
+```

src/hooks/bundled/command-logger/handler.ts

@@ -0,0 +1,64 @@
+/**
+ * Example internal hook handler: Log all commands to a file
+ *
+ * This handler demonstrates how to create a hook that logs all command events
+ * to a centralized log file for audit/debugging purposes.
+ *
+ * To enable this handler, add it to your config:
+ *
+ * ```json
+ * {
+ *   "hooks": {
+ *     "internal": {
+ *       "enabled": true,
+ *       "handlers": [
+ *         {
+ *           "event": "command",
+ *           "module": "./hooks/handlers/command-logger.ts"
+ *         }
+ *       ]
+ *     }
+ *   }
+ * }
+ * ```
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { InternalHookHandler } from '../../internal-hooks.js';
+
+/**
+ * Log all command events to a file
+ */
+const logCommand: InternalHookHandler = async (event) => {
+  // Only trigger on command events
+  if (event.type !== 'command') {
+    return;
+  }
+
+  try {
+    // Create log directory
+    const logDir = path.join(os.homedir(), '.clawdbot', 'logs');
+    await fs.mkdir(logDir, { recursive: true });
+
+    // Append to command log file
+    const logFile = path.join(logDir, 'commands.log');
+    const logLine = JSON.stringify({
+      timestamp: event.timestamp.toISOString(),
+      action: event.action,
+      sessionKey: event.sessionKey,
+      senderId: event.context.senderId ?? 'unknown',
+      source: event.context.commandSource ?? 'unknown',
+    }) + '\n';
+
+    await fs.appendFile(logFile, logLine, 'utf-8');
+  } catch (err) {
+    console.error(
+      '[command-logger] Failed to log command:',
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+};
+
+export default logCommand;

src/hooks/bundled/session-memory/HOOK.md

@@ -0,0 +1,76 @@
+---
+name: session-memory
+description: "Save session context to memory when /new command is issued"
+homepage: https://docs.clawd.bot/internal-hooks#session-memory
+metadata: {"clawdbot":{"emoji":"💾","events":["command:new"],"requires":{"config":["workspace.dir"]},"install":[{"id":"bundled","kind":"bundled","label":"Bundled with Clawdbot"}]}}
+---
+
+# Session Memory Hook
+
+Automatically saves session context to your workspace memory when you issue the `/new` command.
+
+## What It Does
+
+When you run `/new` to start a fresh session:
+
+1. **Finds the previous session** - Uses the pre-reset session entry to locate the correct transcript
+2. **Extracts conversation** - Reads the last 15 lines of conversation from the session
+3. **Generates descriptive slug** - Uses LLM to create a meaningful filename slug based on conversation content
+4. **Saves to memory** - Creates a new file at `<workspace>/memory/YYYY-MM-DD-slug.md`
+5. **Sends confirmation** - Notifies you with the file path
+
+## Output Format
+
+Memory files are created with the following format:
+
+```markdown
+# Session: 2026-01-16 14:30:00 UTC
+
+- **Session Key**: agent:main:main
+- **Session ID**: abc123def456
+- **Source**: telegram
+```
+
+## Filename Examples
+
+The LLM generates descriptive slugs based on your conversation:
+
+- `2026-01-16-vendor-pitch.md` - Discussion about vendor evaluation
+- `2026-01-16-api-design.md` - API architecture planning
+- `2026-01-16-bug-fix.md` - Debugging session
+- `2026-01-16-1430.md` - Fallback timestamp if slug generation fails
+
+## Requirements
+
+- **Config**: `workspace.dir` must be set (automatically configured during onboarding)
+
+The hook uses your configured LLM provider to generate slugs, so it works with any provider (Anthropic, OpenAI, etc.).
+
+## Configuration
+
+No additional configuration required. The hook automatically:
+- Uses your workspace directory (`~/clawd` by default)
+- Uses your configured LLM for slug generation
+- Falls back to timestamp slugs if LLM is unavailable
+
+## Disabling
+
+To disable this hook:
+
+```bash
+clawdbot hooks internal disable session-memory
+```
+
+Or remove it from your config:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "session-memory": { "enabled": false }
+      }
+    }
+  }
+}
+```

src/hooks/bundled/session-memory/handler.ts

@@ -0,0 +1,174 @@
+/**
+ * Session memory hook handler
+ *
+ * Saves session context to memory when /new command is triggered
+ * Creates a new dated memory file with LLM-generated slug
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { ClawdbotConfig } from '../../../config/config.js';
+import { resolveAgentWorkspaceDir } from '../../../agents/agent-scope.js';
+import { resolveAgentIdFromSessionKey } from '../../../routing/session-key.js';
+import type { InternalHookHandler } from '../../internal-hooks.js';
+
+/**
+ * Read recent messages from session file for slug generation
+ */
+async function getRecentSessionContent(sessionFilePath: string): Promise<string | null> {
+  try {
+    const content = await fs.readFile(sessionFilePath, 'utf-8');
+    const lines = content.trim().split('\n');
+
+    // Get last 15 lines (recent conversation)
+    const recentLines = lines.slice(-15);
+
+    // Parse JSONL and extract messages
+    const messages: string[] = [];
+    for (const line of recentLines) {
+      try {
+        const entry = JSON.parse(line);
+        // Session files have entries with type="message" containing a nested message object
+        if (entry.type === 'message' && entry.message) {
+          const msg = entry.message;
+          const role = msg.role;
+          if ((role === 'user' || role === 'assistant') && msg.content) {
+            // Extract text content
+            const text = Array.isArray(msg.content)
+              ? msg.content.find((c: any) => c.type === 'text')?.text
+              : msg.content;
+            if (text && !text.startsWith('/')) {
+              messages.push(`${role}: ${text}`);
+            }
+          }
+        }
+      } catch {
+        // Skip invalid JSON lines
+      }
+    }
+
+    return messages.join('\n');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save session context to memory when /new command is triggered
+ */
+const saveSessionToMemory: InternalHookHandler = async (event) => {
+  // Only trigger on 'new' command
+  if (event.type !== 'command' || event.action !== 'new') {
+    return;
+  }
+
+  try {
+    console.log('[session-memory] Hook triggered for /new command');
+
+    const context = event.context || {};
+    const cfg = context.cfg as ClawdbotConfig | undefined;
+    const agentId = resolveAgentIdFromSessionKey(event.sessionKey);
+    const workspaceDir = cfg
+      ? resolveAgentWorkspaceDir(cfg, agentId)
+      : path.join(os.homedir(), 'clawd');
+    const memoryDir = path.join(workspaceDir, 'memory');
+    await fs.mkdir(memoryDir, { recursive: true });
+
+    // Get today's date for filename
+    const now = new Date(event.timestamp);
+    const dateStr = now.toISOString().split('T')[0]; // YYYY-MM-DD
+
+    // Generate descriptive slug from session using LLM
+    const sessionEntry = (
+      context.previousSessionEntry ||
+      context.sessionEntry ||
+      {}
+    ) as Record<string, unknown>;
+    const currentSessionId = sessionEntry.sessionId as string;
+    const currentSessionFile = sessionEntry.sessionFile as string;
+
+    console.log('[session-memory] Current sessionId:', currentSessionId);
+    console.log('[session-memory] Current sessionFile:', currentSessionFile);
+    console.log('[session-memory] cfg present:', !!cfg);
+
+    const sessionFile = currentSessionFile || undefined;
+
+    let slug: string | null = null;
+    let sessionContent: string | null = null;
+
+    if (sessionFile) {
+      // Get recent conversation content
+      sessionContent = await getRecentSessionContent(sessionFile);
+      console.log('[session-memory] sessionContent length:', sessionContent?.length || 0);
+
+      if (sessionContent && cfg) {
+        console.log('[session-memory] Calling generateSlugViaLLM...');
+        // Dynamically import the LLM slug generator (avoids module caching issues)
+        // When compiled, handler is at dist/hooks/bundled/session-memory/handler.js
+        // Going up ../.. puts us at dist/hooks/, so just add llm-slug-generator.js
+        const clawdbotRoot = path.resolve(path.dirname(import.meta.url.replace('file://', '')), '../..');
+        const slugGenPath = path.join(clawdbotRoot, 'llm-slug-generator.js');
+        const { generateSlugViaLLM } = await import(slugGenPath);
+
+        // Use LLM to generate a descriptive slug
+        slug = await generateSlugViaLLM({ sessionContent, cfg });
+        console.log('[session-memory] Generated slug:', slug);
+      }
+    }
+
+    // If no slug, use timestamp
+    if (!slug) {
+      const timeSlug = now.toISOString().split('T')[1]!.split('.')[0]!.replace(/:/g, '');
+      slug = timeSlug.slice(0, 4); // HHMM
+      console.log('[session-memory] Using fallback timestamp slug:', slug);
+    }
+
+    // Create filename with date and slug
+    const filename = `${dateStr}-${slug}.md`;
+    const memoryFilePath = path.join(memoryDir, filename);
+    console.log('[session-memory] Generated filename:', filename);
+    console.log('[session-memory] Full path:', memoryFilePath);
+
+    // Format time as HH:MM:SS UTC
+    const timeStr = now.toISOString().split('T')[1]!.split('.')[0];
+
+    // Extract context details
+    const sessionId = (sessionEntry.sessionId as string) || 'unknown';
+    const source = (context.commandSource as string) || 'unknown';
+
+    // Build Markdown entry
+    const entryParts = [
+      `# Session: ${dateStr} ${timeStr} UTC`,
+      '',
+      `- **Session Key**: ${event.sessionKey}`,
+      `- **Session ID**: ${sessionId}`,
+      `- **Source**: ${source}`,
+      '',
+    ];
+
+    // Include conversation content if available
+    if (sessionContent) {
+      entryParts.push('## Conversation Summary', '', sessionContent, '');
+    }
+
+    const entry = entryParts.join('\n');
+
+    // Write to new memory file
+    await fs.writeFile(memoryFilePath, entry, 'utf-8');
+    console.log('[session-memory] Memory file written successfully');
+
+    // Send confirmation message to user with filename
+    const relPath = memoryFilePath.replace(os.homedir(), '~');
+    const confirmMsg = `💾 Session context saved to memory before reset.\n📄 ${relPath}`;
+    event.messages.push(confirmMsg);
+    console.log('[session-memory] Confirmation message queued:', confirmMsg);
+  } catch (err) {
+    console.error(
+      '[session-memory] Failed to save session memory:',
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+};
+
+export default saveSessionToMemory;