aegis-bridge 2.2.2

package/dist/hook.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/**
+ * hook.ts — Claude Code SessionStart hook for Aegis.
+ *
+ * Writes session_id → window_id mapping to ~/.aegis/session_map.json.
+ * Falls back to ~/.manus/ for backward compatibility.
+ * Called by CC's hook system, reads payload from stdin.
+ *
+ * Install: add to ~/.claude/settings.json:
+ * {
+ *   "hooks": {
+ *     "SessionStart": [{
+ *       "hooks": [{ "type": "command", "command": "node /path/to/dist/hook.js", "timeout": 5 }]
+ *     }]
+ *   }
+ * }
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { stopSignalsSchema, sessionMapSchema } from './validation.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Use ~/.aegis if it exists, fall back to ~/.manus for backward compat
+const AEGIS_DIR = join(homedir(), '.aegis');
+const MANUS_DIR = join(homedir(), '.manus');
+const BRIDGE_DIR = existsSync(AEGIS_DIR) ? AEGIS_DIR : MANUS_DIR;
+const MAP_FILE = join(BRIDGE_DIR, 'session_map.json');
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const TMUX_PANE_RE = /^%\d+$/;
+/** Handle Stop/StopFailure events.
+ *  Writes a signal file that the Aegis monitor can detect.
+ *  Issue #15: StopFailure fires on API errors (rate limit, auth failure).
+ */
+function handleStopEvent(sessionId, event, payload) {
+    const signalFile = join(BRIDGE_DIR, 'stop_signals.json');
+    let signals = {};
+    if (existsSync(signalFile)) {
+        try {
+            const parsed = stopSignalsSchema.safeParse(JSON.parse(readFileSync(signalFile, 'utf-8')));
+            if (parsed.success) {
+                signals = parsed.data;
+            }
+            else {
+                console.warn('stop_signals.json failed validation, starting fresh');
+            }
+        }
+        catch { /* fresh */ }
+    }
+    signals[sessionId] = {
+        event,
+        timestamp: Date.now(),
+        // StopFailure may include error info in the payload
+        error: payload.error || payload.message || null,
+        error_details: payload.error_details ?? null,
+        last_assistant_message: payload.last_assistant_message ?? null,
+        agent_id: payload.agent_id ?? null,
+        stop_reason: payload.stop_reason ?? null,
+    };
+    // Atomic write: write to temp file then rename (prevents partial writes on crash)
+    const tmpSignalFile = signalFile + '.tmp';
+    writeFileSync(tmpSignalFile, JSON.stringify(signals, null, 2));
+    renameSync(tmpSignalFile, signalFile);
+    console.error(`Aegis hook: ${event} for session ${sessionId.slice(0, 8)}...`);
+}
+function main() {
+    // Check for --install flag
+    if (process.argv.includes('--install')) {
+        install();
+        return;
+    }
+    // Read payload from stdin
+    let payload;
+    try {
+        const input = readFileSync(0, 'utf-8'); // stdin = fd 0
+        payload = JSON.parse(input);
+    }
+    catch { /* malformed or empty stdin — nothing to do */
+        process.exit(0);
+    }
+    const sessionId = payload.session_id || '';
+    const cwd = payload.cwd || '';
+    const event = payload.hook_event_name || '';
+    if (!sessionId) {
+        process.exit(0);
+    }
+    // Handle Stop and StopFailure events — write signal file for monitor
+    if (event === 'Stop' || event === 'StopFailure') {
+        handleStopEvent(sessionId, event, payload);
+        process.exit(0);
+    }
+    if (event !== 'SessionStart') {
+        process.exit(0);
+    }
+    if (!UUID_RE.test(sessionId)) {
+        console.error(`Invalid session_id: ${sessionId}`);
+        process.exit(0);
+    }
+    // Get tmux window info
+    const tmuxPane = process.env.TMUX_PANE;
+    if (!tmuxPane) {
+        console.error('TMUX_PANE not set');
+        process.exit(0);
+    }
+    if (!TMUX_PANE_RE.test(tmuxPane)) {
+        console.error(`Invalid TMUX_PANE: ${tmuxPane}`);
+        process.exit(0);
+    }
+    let tmuxInfo;
+    try {
+        tmuxInfo = execFileSync('tmux', ['display-message', '-t', tmuxPane, '-p', '#{session_name}:#{window_id}:#{window_name}'], { encoding: 'utf-8' }).trim();
+    }
+    catch { /* tmux not running or pane not found */
+        console.error('Failed to get tmux info');
+        process.exit(0);
+    }
+    const parts = tmuxInfo.split(':');
+    if (parts.length < 3) {
+        process.exit(0);
+    }
+    const [sessionName, windowId, windowName] = parts;
+    const key = `${sessionName}:${windowId}`;
+    // Read-modify-write session_map
+    mkdirSync(BRIDGE_DIR, { recursive: true });
+    let sessionMap = {};
+    if (existsSync(MAP_FILE)) {
+        try {
+            const parsed = sessionMapSchema.safeParse(JSON.parse(readFileSync(MAP_FILE, 'utf-8')));
+            if (parsed.success) {
+                sessionMap = parsed.data;
+            }
+            else {
+                console.warn('session_map.json failed validation, starting fresh');
+            }
+        }
+        catch { /* fresh map */ }
+    }
+    sessionMap[key] = {
+        session_id: sessionId,
+        cwd,
+        window_name: windowName || '',
+        transcript_path: payload.transcript_path || null,
+        permission_mode: payload.permission_mode || null,
+        agent_id: payload.agent_id || null,
+        source: payload.source || null,
+        agent_type: payload.agent_type || null,
+        model: payload.model || null,
+        written_at: Date.now(),
+    };
+    // Atomic write: write to temp file then rename (prevents race-condition data loss)
+    const tmpMapFile = MAP_FILE + '.tmp';
+    writeFileSync(tmpMapFile, JSON.stringify(sessionMap, null, 2));
+    renameSync(tmpMapFile, MAP_FILE);
+    console.error(`Aegis hook: mapped ${key} -> ${sessionId}`);
+}
+function install() {
+    const settingsPath = join(homedir(), '.claude', 'settings.json');
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        }
+        catch { /* corrupted or unreadable settings file */
+            console.error(`Failed to read ${settingsPath}`);
+            process.exit(1);
+        }
+    }
+    const hookCommand = `node ${join(__dirname, 'hook.js')}`;
+    const hooks = (settings.hooks || {});
+    const sessionStart = (hooks.SessionStart || []);
+    // Check if already installed
+    const isInstalled = sessionStart.some(entry => entry.hooks?.some(h => h.command?.includes('aegis') || h.command?.includes('manus') || h.command?.includes('hook.js')));
+    if (isInstalled) {
+        console.log('Aegis hook already installed');
+        return;
+    }
+    sessionStart.push({
+        hooks: [{ type: 'command', command: hookCommand, timeout: 5 }]
+    });
+    hooks.SessionStart = sessionStart;
+    // Issue #15: Also register Stop and StopFailure hooks
+    const hookEntry = { hooks: [{ type: 'command', command: hookCommand, timeout: 5 }] };
+    for (const event of ['Stop', 'StopFailure']) {
+        const existing = (hooks[event] || []);
+        const alreadyInstalled = existing.some(entry => entry.hooks?.some(h => h.command?.includes('aegis') || h.command?.includes('manus') || h.command?.includes('hook.js')));
+        if (!alreadyInstalled) {
+            existing.push({ ...hookEntry });
+            hooks[event] = existing;
+        }
+    }
+    settings.hooks = hooks;
+    mkdirSync(join(homedir(), '.claude'), { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    console.log(`Aegis hook installed in ${settingsPath}`);
+}
+main();
+//# sourceMappingURL=hook.js.map

package/dist/hooks.d.ts

@@ -0,0 +1,32 @@
+/**
+ * hooks.ts — HTTP hook receiver for Claude Code hook events.
+ *
+ * Claude Code supports type: "http" hooks that POST JSON events to a URL.
+ * This module provides a route handler that receives these events and
+ * forwards them to SSE subscribers.
+ *
+ * Hook URL pattern: POST /v1/hooks/{eventName}?sessionId={id}
+ * Session identification: X-Session-Id header or sessionId query param.
+ *
+ * Decision events (PreToolUse, PermissionRequest) return a response body
+ * that CC uses to approve/reject tool calls.
+ *
+ * Issue #169: Phase 1 — HTTP hooks infrastructure.
+ * Issue #169: Phase 3 — Hook-driven status detection.
+ */
+import type { FastifyInstance } from 'fastify';
+import type { SessionManager } from './session.js';
+import type { SessionEventBus } from './events.js';
+import type { MetricsCollector } from './metrics.js';
+export interface HookRouteDeps {
+    sessions: SessionManager;
+    eventBus: SessionEventBus;
+    metrics?: MetricsCollector;
+}
+/**
+ * Register the hooks endpoint on the Fastify app.
+ *
+ * This MUST be called before auth middleware is set up, OR the /v1/hooks
+ * path must be added to the auth skip list in setupAuth().
+ */
+export declare function registerHookRoutes(app: FastifyInstance, deps: HookRouteDeps): void;

package/dist/hooks.js

@@ -0,0 +1,279 @@
+/**
+ * hooks.ts — HTTP hook receiver for Claude Code hook events.
+ *
+ * Claude Code supports type: "http" hooks that POST JSON events to a URL.
+ * This module provides a route handler that receives these events and
+ * forwards them to SSE subscribers.
+ *
+ * Hook URL pattern: POST /v1/hooks/{eventName}?sessionId={id}
+ * Session identification: X-Session-Id header or sessionId query param.
+ *
+ * Decision events (PreToolUse, PermissionRequest) return a response body
+ * that CC uses to approve/reject tool calls.
+ *
+ * Issue #169: Phase 1 — HTTP hooks infrastructure.
+ * Issue #169: Phase 3 — Hook-driven status detection.
+ */
+/** CC hook events that require a decision response. */
+const DECISION_EVENTS = new Set(['PreToolUse', 'PermissionRequest']);
+/** Permission modes that should be auto-approved via hook response. */
+const AUTO_APPROVE_MODES = new Set(['bypassPermissions', 'dontAsk', 'acceptEdits', 'plan', 'auto']);
+/** Default timeout for waiting on client permission decision (ms). */
+const PERMISSION_TIMEOUT_MS = 10_000;
+/** Default timeout for waiting on external answer to AskUserQuestion (ms). */
+const ANSWER_TIMEOUT_MS = parseInt(process.env.ANSWER_TIMEOUT_MS || '30000', 10);
+/** Valid permission_mode values accepted by Claude Code. */
+const VALID_PERMISSION_MODES = new Set(['default', 'plan', 'bypassPermissions']);
+/** Valid CC hook event names (allow any for extensibility, but these are known). */
+const KNOWN_HOOK_EVENTS = new Set([
+    'Stop',
+    'StopFailure',
+    'PreToolUse',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'Notification',
+    'PermissionRequest',
+    'SessionStart',
+    'SessionEnd',
+    'SubagentStart',
+    'SubagentStop',
+    'TaskCompleted',
+    'TeammateIdle',
+    'PreCompact',
+    'PostCompact',
+    'UserPromptSubmit',
+    'WorktreeCreate',
+    'WorktreeCreateFailed',
+    'WorktreeRemove',
+    'WorktreeRemoveFailed',
+    'Elicitation',
+    'ElicitationResult',
+    'FileChanged',
+    'CwdChanged',
+]);
+/** Hook events that are informational (logged + forwarded to SSE, no status change). */
+const INFORMATIONAL_EVENTS = new Set([
+    'Notification',
+    'FileChanged',
+    'CwdChanged',
+]);
+/** Map hook event names to the UIState they imply. */
+function hookToUIState(eventName) {
+    switch (eventName) {
+        case 'Stop':
+        case 'TaskCompleted':
+        case 'SessionEnd':
+        case 'PostCompact': return 'idle';
+        case 'StopFailure':
+        case 'PostToolUseFailure': return 'error';
+        case 'PreToolUse':
+        case 'PostToolUse':
+        case 'SubagentStart':
+        case 'UserPromptSubmit':
+        case 'Elicitation':
+        case 'ElicitationResult': return 'working';
+        case 'PreCompact': return 'compacting';
+        case 'PermissionRequest': return 'permission_prompt';
+        case 'TeammateIdle': return 'idle';
+        default: return null;
+    }
+}
+/** Extract question text from AskUserQuestion tool_input. */
+function extractQuestionText(toolInput) {
+    if (!toolInput)
+        return '';
+    const questions = toolInput.questions;
+    if (!questions || !Array.isArray(questions) || questions.length === 0)
+        return '';
+    const first = questions[0];
+    return first?.question || '';
+}
+/**
+ * Register the hooks endpoint on the Fastify app.
+ *
+ * This MUST be called before auth middleware is set up, OR the /v1/hooks
+ * path must be added to the auth skip list in setupAuth().
+ */
+export function registerHookRoutes(app, deps) {
+    app.post('/v1/hooks/:eventName', async (req, reply) => {
+        const { eventName } = req.params;
+        // Issue #349: Validate event name against known list to prevent injection
+        if (!KNOWN_HOOK_EVENTS.has(eventName)) {
+            return reply.status(400).send({ error: `Unknown hook event: ${eventName}` });
+        }
+        const sessionId = req.headers['x-session-id'] || req.query.sessionId;
+        if (!sessionId) {
+            return reply.status(400).send({ error: 'Missing session ID — provide X-Session-Id header or sessionId query param' });
+        }
+        const session = deps.sessions.getSession(sessionId);
+        if (!session) {
+            return reply.status(404).send({ error: `Session ${sessionId} not found` });
+        }
+        // Issue #88: Track active subagents
+        const hookBody = req.body;
+        if (eventName === 'SubagentStart') {
+            const agentName = hookBody?.agent_name || hookBody?.tool_input?.command || 'unknown';
+            deps.sessions.addSubagent(sessionId, agentName);
+            deps.eventBus.emit(sessionId, {
+                event: 'subagent_start',
+                sessionId,
+                timestamp: new Date().toISOString(),
+                data: { agentName },
+            });
+        }
+        else if (eventName === 'SubagentStop') {
+            const agentName = hookBody?.agent_name || 'unknown';
+            deps.sessions.removeSubagent(sessionId, agentName);
+            deps.eventBus.emit(sessionId, {
+                event: 'subagent_stop',
+                sessionId,
+                timestamp: new Date().toISOString(),
+                data: { agentName },
+            });
+        }
+        // Issue #89 L26: WorktreeCreate/Remove hooks — informational tracking only
+        if (eventName === 'WorktreeCreate' || eventName === 'WorktreeCreateFailed' ||
+            eventName === 'WorktreeRemove' || eventName === 'WorktreeRemoveFailed') {
+            console.log(`Hooks: ${eventName} for session ${sessionId}`);
+        }
+        // Informational events — log and forward to SSE (already forwarded below via emitHook)
+        if (INFORMATIONAL_EVENTS.has(eventName)) {
+            console.log(`Hooks: ${eventName} for session ${sessionId}`);
+        }
+        // PreCompact/PostCompact — update activity timestamp
+        if (eventName === 'PreCompact' || eventName === 'PostCompact') {
+            session.lastActivity = Date.now();
+        }
+        // Forward the raw hook event to SSE subscribers
+        deps.eventBus.emitHook(sessionId, eventName, req.body);
+        // Issue #89 L25: Capture model field from hook payload for dashboard display
+        const hookPayload = req.body;
+        if (hookPayload?.model && typeof hookPayload.model === 'string') {
+            deps.sessions.updateSessionModel(sessionId, hookPayload.model);
+        }
+        // Issue #89 L24: Validate permission_mode from PermissionRequest hook
+        if (eventName === 'PermissionRequest') {
+            const rawMode = hookBody?.permission_mode;
+            if (rawMode !== undefined && !VALID_PERMISSION_MODES.has(rawMode)) {
+                console.warn(`Hooks: invalid permission_mode "${rawMode}" from PermissionRequest, using "default"`);
+                hookBody.permission_mode = 'default';
+            }
+        }
+        // Issue #169 Phase 3: Update session status from hook event
+        // Issue #87: Extract timestamp from hook payload for latency calculation
+        const hookReceivedAt = Date.now();
+        const hookEventTimestamp = hookPayload?.timestamp
+            ? new Date(hookPayload.timestamp).getTime()
+            : undefined;
+        // Issue #87: Record hook latency if we have a timestamp from the payload
+        if (hookEventTimestamp && deps.metrics) {
+            const latency = hookReceivedAt - hookEventTimestamp;
+            if (latency >= 0) {
+                deps.metrics.recordHookLatency(sessionId, latency);
+            }
+        }
+        const prevStatus = deps.sessions.updateStatusFromHook(sessionId, eventName, hookEventTimestamp);
+        const newStatus = hookToUIState(eventName);
+        // Emit SSE status event only when the hook implies a state change
+        if (newStatus && prevStatus !== newStatus) {
+            switch (eventName) {
+                case 'Stop':
+                    deps.eventBus.emitStatus(sessionId, 'idle', 'Claude finished (hook: Stop)');
+                    break;
+                case 'PreToolUse':
+                case 'PostToolUse':
+                    deps.eventBus.emitStatus(sessionId, 'working', 'Claude is working (hook: tool use)');
+                    break;
+                case 'PreCompact':
+                    deps.eventBus.emitStatus(sessionId, 'compacting', 'Claude is compacting context (hook: PreCompact)');
+                    break;
+                case 'PostCompact':
+                    deps.eventBus.emitStatus(sessionId, 'idle', 'Compaction complete (hook: PostCompact)');
+                    break;
+                case 'Elicitation':
+                    deps.eventBus.emitStatus(sessionId, 'working', 'Claude is performing MCP elicitation (hook: Elicitation)');
+                    break;
+                case 'ElicitationResult':
+                    deps.eventBus.emitStatus(sessionId, 'working', 'Elicitation result received (hook: ElicitationResult)');
+                    break;
+                case 'PermissionRequest':
+                    deps.eventBus.emitApproval(sessionId, req.body?.permission_prompt
+                        || 'Permission requested (hook)');
+                    break;
+            }
+        }
+        // Decision events need a response body that CC uses
+        // Format: { hookSpecificOutput: { hookEventName, permissionDecision, reason? } }
+        if (DECISION_EVENTS.has(eventName)) {
+            const hookBody = req.body;
+            const toolName = hookBody?.tool_name || '';
+            const permissionPrompt = hookBody?.permission_prompt || '';
+            if (eventName === 'PreToolUse') {
+                // Issue #336: Intercept AskUserQuestion for headless question answering
+                if (toolName === 'AskUserQuestion') {
+                    const toolInput = hookBody?.tool_input;
+                    const toolUseId = hookBody?.tool_use_id || '';
+                    const questionText = extractQuestionText(toolInput);
+                    // Emit ask_question SSE event for external clients
+                    deps.eventBus.emit(sessionId, {
+                        event: 'status',
+                        sessionId,
+                        timestamp: new Date().toISOString(),
+                        data: { status: 'ask_question', questionId: toolUseId, question: questionText },
+                    });
+                    console.log(`Hooks: AskUserQuestion for session ${sessionId} — waiting for answer (timeout: ${ANSWER_TIMEOUT_MS}ms)`);
+                    const answer = await deps.sessions.waitForAnswer(sessionId, toolUseId, questionText, ANSWER_TIMEOUT_MS);
+                    if (answer !== null) {
+                        console.log(`Hooks: AskUserQuestion answered for session ${sessionId}`);
+                        return reply.status(200).send({
+                            hookSpecificOutput: {
+                                hookEventName: 'PreToolUse',
+                                permissionDecision: 'allow',
+                                updatedInput: { answer },
+                            },
+                        });
+                    }
+                    // Timeout: allow without answer (CC shows question to user in terminal)
+                    console.log(`Hooks: AskUserQuestion timeout for session ${sessionId} — allowing without answer`);
+                }
+                // Default: allow without modification
+                return reply.status(200).send({
+                    hookSpecificOutput: {
+                        hookEventName: 'PreToolUse',
+                        permissionDecision: 'allow',
+                    },
+                });
+            }
+            if (eventName === 'PermissionRequest') {
+                // Issue #284: Hook-based permission approval.
+                // Auto-approve modes respond immediately; others wait for client.
+                const permMode = session.permissionMode || 'default';
+                if (AUTO_APPROVE_MODES.has(permMode)) {
+                    console.log(`Hooks: auto-approving PermissionRequest for session ${sessionId} (mode: ${permMode})`);
+                    return reply.status(200).send({
+                        hookSpecificOutput: {
+                            hookEventName: 'PermissionRequest',
+                            permissionDecision: 'allow',
+                        },
+                    });
+                }
+                // Non-auto-approve: wait for client to approve/reject via API.
+                // Store pending permission and block until resolved or timeout.
+                console.log(`Hooks: waiting for client permission decision for session ${sessionId}`);
+                const decision = await deps.sessions.waitForPermissionDecision(sessionId, PERMISSION_TIMEOUT_MS, toolName, permissionPrompt);
+                const decisionLabel = decision === 'allow' ? 'approved' : 'rejected';
+                console.log(`Hooks: PermissionRequest for session ${sessionId} — ${decisionLabel} by client`);
+                return reply.status(200).send({
+                    hookSpecificOutput: {
+                        hookEventName: 'PermissionRequest',
+                        permissionDecision: decision,
+                    },
+                });
+            }
+            return reply.status(200).send({ ok: true });
+        }
+        // Non-decision events: simple acknowledgement
+        return reply.status(200).send({ ok: true });
+    });
+}
+//# sourceMappingURL=hooks.js.map

package/dist/jsonl-watcher.d.ts

@@ -0,0 +1,57 @@
+/**
+ * jsonl-watcher.ts — fs.watch()-based JSONL file watcher.
+ *
+ * Replaces polling-based JSONL reading in the monitor with near-instant
+ * file change detection. Uses fs.watch() with debouncing to avoid
+ * duplicate events from rapid writes.
+ *
+ * Issue #84: Replace JSONL polling with fs.watch.
+ */
+import { type ParsedEntry } from './transcript.js';
+export interface JsonlWatcherEvent {
+    sessionId: string;
+    messages: ParsedEntry[];
+    newOffset: number;
+    /** True if the file was truncated (e.g. after /clear). */
+    truncated: boolean;
+}
+export interface JsonlWatcherConfig {
+    /** Debounce interval in ms to coalesce rapid writes (default: 100). */
+    debounceMs: number;
+}
+/**
+ * Watches JSONL files for changes and emits parsed entries.
+ *
+ * Usage:
+ *   const watcher = new JsonlWatcher();
+ *   watcher.onEntries((event) => { ... });
+ *   watcher.watch('session-123', '/path/to/session.jsonl', 0);
+ *   watcher.unwatch('session-123');
+ *   watcher.destroy();
+ */
+export declare class JsonlWatcher {
+    private entries;
+    private listeners;
+    private config;
+    constructor(config?: Partial<JsonlWatcherConfig>);
+    /** Register a callback for new entries. */
+    onEntries(listener: (event: JsonlWatcherEvent) => void): () => void;
+    /** Start watching a JSONL file for a session.
+     *  @param initialOffset - byte offset to start reading from (usually 0 or current session.monitorOffset).
+     */
+    watch(sessionId: string, jsonlPath: string, initialOffset: number): void;
+    /** Stop watching a session's JSONL file. */
+    unwatch(sessionId: string): void;
+    /** Update the offset for a session (e.g. after manual read during discovery). */
+    setOffset(sessionId: string, offset: number): void;
+    /** Check if a session is being watched. */
+    isWatching(sessionId: string): boolean;
+    /** Get the current offset for a watched session. */
+    getOffset(sessionId: string): number | undefined;
+    /** Stop all watchers and clean up. */
+    destroy(): void;
+    /** Schedule a debounced read for a session. */
+    private scheduleRead;
+    /** Read new bytes from the JSONL file and emit entries. */
+    private readAndEmit;
+}