aegis-bridge 0.1.0

package/dist/tool-registry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * tool-registry.ts — Tool usage tracking and registry for CC tool introspection.
+ *
+ * Parses tool_use messages from JSONL transcripts to build per-session
+ * and global tool usage metrics. Exposes API endpoints for observability.
+ *
+ * Issue #704: Tool registry and schema validation for CC tool introspection.
+ */
+import type { ParsedEntry } from './transcript.js';
+/** Known CC tool definitions with metadata. */
+export interface ToolDefinition {
+    name: string;
+    category: string;
+    description: string;
+    permissionLevel: string;
+}
+/** Per-tool usage stats within a session. */
+export interface ToolUsageRecord {
+    name: string;
+    count: number;
+    lastUsedAt: number;
+    firstUsedAt: number;
+    errors: number;
+}
+/** Tool registry: known tools + per-session usage tracking. */
+export declare class ToolRegistry {
+    private sessionUsage;
+    /** Built-in CC tool definitions (from CC src/tools/). */
+    private readonly tools;
+    /** Process parsed entries and extract tool usage. */
+    processEntries(sessionId: string, entries: ParsedEntry[]): void;
+    /** Get tool usage for a session, sorted by count descending. */
+    getSessionTools(sessionId: string): ToolUsageRecord[];
+    /** Get all known CC tool definitions. */
+    getToolDefinitions(): ToolDefinition[];
+    /** Get a tool definition by name. */
+    getToolDefinition(name: string): ToolDefinition | undefined;
+    /** Clean up session data. */
+    cleanupSession(sessionId: string): void;
+}

package/dist/tool-registry.js

@@ -0,0 +1,83 @@
+/**
+ * tool-registry.ts — Tool usage tracking and registry for CC tool introspection.
+ *
+ * Parses tool_use messages from JSONL transcripts to build per-session
+ * and global tool usage metrics. Exposes API endpoints for observability.
+ *
+ * Issue #704: Tool registry and schema validation for CC tool introspection.
+ */
+/** Tool registry: known tools + per-session usage tracking. */
+export class ToolRegistry {
+    sessionUsage = new Map();
+    /** Built-in CC tool definitions (from CC src/tools/). */
+    tools = [
+        { name: 'Read', category: 'read', description: 'Read file contents', permissionLevel: 'read' },
+        { name: 'Write', category: 'write', description: 'Write file contents', permissionLevel: 'write' },
+        { name: 'Edit', category: 'edit', description: 'Edit file with search/replace', permissionLevel: 'edit' },
+        { name: 'MultiEdit', category: 'edit', description: 'Multiple edits in one operation', permissionLevel: 'edit' },
+        { name: 'Bash', category: 'bash', description: 'Execute shell commands', permissionLevel: 'bash' },
+        { name: 'Glob', category: 'search', description: 'Find files matching pattern', permissionLevel: 'read' },
+        { name: 'Grep', category: 'search', description: 'Search file contents', permissionLevel: 'read' },
+        { name: 'ListFiles', category: 'search', description: 'List directory contents', permissionLevel: 'read' },
+        { name: 'TodoWrite', category: 'edit', description: 'Update todo list', permissionLevel: 'edit' },
+        { name: 'TodoRead', category: 'read', description: 'Read todo list', permissionLevel: 'read' },
+        { name: 'WebFetch', category: 'read', description: 'Fetch web page content', permissionLevel: 'read' },
+        { name: 'NotebookRead', category: 'read', description: 'Read notebook cells', permissionLevel: 'read' },
+        { name: 'NotebookEdit', category: 'edit', description: 'Edit notebook cells', permissionLevel: 'edit' },
+        { name: 'AskUserQuestion', category: 'agent', description: 'Ask user for clarification', permissionLevel: 'read' },
+        { name: 'AgentTool', category: 'agent', description: 'Spawn sub-agent for parallel execution', permissionLevel: 'agent' },
+        { name: 'MCPTool', category: 'mcp', description: 'MCP server tool invocation', permissionLevel: 'mcp' },
+    ];
+    /** Process parsed entries and extract tool usage. */
+    processEntries(sessionId, entries) {
+        let usage = this.sessionUsage.get(sessionId);
+        if (!usage) {
+            usage = new Map();
+            this.sessionUsage.set(sessionId, usage);
+        }
+        const now = Date.now();
+        for (const entry of entries) {
+            if (entry.contentType === 'tool_use' && entry.toolName) {
+                const existing = usage.get(entry.toolName);
+                if (existing) {
+                    existing.count++;
+                    existing.lastUsedAt = now;
+                }
+                else {
+                    usage.set(entry.toolName, {
+                        name: entry.toolName,
+                        count: 1,
+                        lastUsedAt: now,
+                        firstUsedAt: now,
+                        errors: 0,
+                    });
+                }
+            }
+            if (entry.contentType === 'tool_error' && entry.toolName) {
+                const existing = usage.get(entry.toolName);
+                if (existing) {
+                    existing.errors++;
+                }
+            }
+        }
+    }
+    /** Get tool usage for a session, sorted by count descending. */
+    getSessionTools(sessionId) {
+        const usage = this.sessionUsage.get(sessionId);
+        if (!usage)
+            return [];
+        return [...usage.values()].sort((a, b) => b.count - a.count);
+    }
+    /** Get all known CC tool definitions. */
+    getToolDefinitions() {
+        return [...this.tools];
+    }
+    /** Get a tool definition by name. */
+    getToolDefinition(name) {
+        return this.tools.find(t => t.name === name);
+    }
+    /** Clean up session data. */
+    cleanupSession(sessionId) {
+        this.sessionUsage.delete(sessionId);
+    }
+}

package/dist/transcript.d.ts

@@ -0,0 +1,63 @@
+/**
+ * transcript.ts — JSONL transcript parser for Claude Code sessions.
+ *
+ * Port of CCBot's transcript_parser.py.
+ * Reads CC session JSONL files and extracts structured messages.
+ */
+export interface ParsedEntry {
+    role: 'user' | 'assistant' | 'system';
+    contentType: 'text' | 'thinking' | 'tool_use' | 'tool_result' | 'tool_error' | 'permission_request' | 'progress';
+    text: string;
+    toolName?: string;
+    toolUseId?: string;
+    timestamp?: string;
+}
+interface ContentBlock {
+    type: string;
+    text?: string;
+    thinking?: string;
+    name?: string;
+    id?: string;
+    tool_use_id?: string;
+    input?: Record<string, unknown>;
+    content?: unknown;
+    is_error?: boolean;
+}
+/** Issue #488: Cumulative token usage extracted from a batch of JSONL entries. */
+export interface TokenUsageDelta {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+}
+export interface JsonlEntry {
+    type: string;
+    message?: {
+        role: string;
+        content: string | ContentBlock[];
+        stop_reason?: string;
+        /** Token usage reported by the model (present on assistant messages). */
+        usage?: {
+            input_tokens?: number;
+            output_tokens?: number;
+            cache_creation_input_tokens?: number;
+            cache_read_input_tokens?: number;
+        };
+    };
+    timestamp?: string;
+    tool_use_id?: string;
+    data?: Record<string, unknown>;
+}
+/** Parse entries from JSONL data. */
+export declare function parseEntries(entries: JsonlEntry[]): ParsedEntry[];
+/** Issue #488: Sum token usage across a batch of raw JSONL entries. */
+export declare function extractTokenDelta(raw: JsonlEntry[]): TokenUsageDelta;
+/** Read JSONL file from byte offset, return new entries + new offset. */
+export declare function readNewEntries(filePath: string, fromOffset: number): Promise<{
+    entries: ParsedEntry[];
+    newOffset: number;
+    raw: JsonlEntry[];
+}>;
+/** Find the JSONL file for a session ID. */
+export declare function findSessionFile(sessionId: string, claudeProjectsDir?: string): Promise<string | null>;
+export {};

package/dist/transcript.js

@@ -0,0 +1,284 @@
+/**
+ * transcript.ts — JSONL transcript parser for Claude Code sessions.
+ *
+ * Port of CCBot's transcript_parser.py.
+ * Reads CC session JSONL files and extracts structured messages.
+ */
+import { readFile, open, access } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { readdir } from 'node:fs/promises';
+import { sessionsIndexSchema } from './validation.js';
+import { safeJsonParse, safeJsonParseSchema } from './safe-json.js';
+/** Default Claude projects directory */
+const DEFAULT_CLAUDE_PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+/** Parse a single JSONL line. Returns null if not parseable.
+ *  Issue #823: Logs at error level when a non-empty line is dropped. */
+function parseLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed[0] !== '{') {
+        // Lines that are blank or don't start with '{' are expected (separators, comments)
+        return null;
+    }
+    const parsed = safeJsonParse(trimmed, 'JSONL line');
+    if (!parsed.ok) {
+        // Issue #823: Log malformed JSON lines so data loss is visible
+        console.error(`parseLine: dropping malformed JSONL line (${parsed.error}): ${trimmed.slice(0, 200)}`);
+        return null;
+    }
+    return parsed.data;
+}
+/** Summarize a tool_use block. */
+function summarizeTool(name, input) {
+    switch (name) {
+        case 'Read':
+        case 'ReadNotebook':
+            return `📖 **Read** ${input.file_path || input.path || ''}`;
+        case 'Write':
+        case 'MultiWrite':
+            return `✏️ **Write** ${input.file_path || input.path || ''}`;
+        case 'Edit':
+            return `🔧 **Edit** ${input.file_path || input.path || ''}`;
+        case 'Bash':
+        case 'Terminal':
+            return `💻 **Bash** \`${String(input.command || input.cmd || '').slice(0, 80)}\``;
+        case 'Grep':
+        case 'Search':
+            return `🔍 **Search** \`${input.pattern || input.query || ''}\``;
+        case 'Glob':
+        case 'ListFiles':
+            return `📁 **Glob** \`${input.pattern || input.path || ''}\``;
+        case 'AskUserQuestion':
+            return `❓ **Question**: ${input.question || ''}`;
+        case 'TodoWrite':
+            return `📝 **Todo** updated`;
+        default:
+            return `🔧 **${name}**`;
+    }
+}
+/** Parse entries from JSONL data. */
+export function parseEntries(entries) {
+    const results = [];
+    const pendingTools = new Map(); // tool_use_id -> summary
+    for (const entry of entries) {
+        if (entry.type === 'progress') {
+            const text = entry.data ? JSON.stringify(entry.data) : '';
+            if (text.trim()) {
+                results.push({ role: 'system', contentType: 'progress', text, timestamp: entry.timestamp });
+            }
+            continue;
+        }
+        if (!entry.message)
+            continue;
+        const role = entry.message.role;
+        const content = entry.message.content;
+        const timestamp = entry.timestamp;
+        if (typeof content === 'string') {
+            // Simple text message
+            if (content.trim()) {
+                results.push({ role, contentType: 'text', text: content.trim(), timestamp });
+            }
+            continue;
+        }
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            switch (block.type) {
+                case 'text':
+                    if (block.text?.trim()) {
+                        results.push({ role, contentType: 'text', text: block.text.trim(), timestamp });
+                    }
+                    break;
+                case 'thinking':
+                    if (block.thinking?.trim()) {
+                        results.push({ role, contentType: 'thinking', text: block.thinking.trim(), timestamp });
+                    }
+                    break;
+                case 'tool_use': {
+                    const name = block.name || 'unknown';
+                    const input = (block.input || {});
+                    const summary = summarizeTool(name, input);
+                    if (block.id) {
+                        pendingTools.set(block.id, summary);
+                    }
+                    results.push({
+                        role: 'assistant',
+                        contentType: 'tool_use',
+                        text: summary,
+                        toolName: name,
+                        toolUseId: block.id,
+                        timestamp,
+                    });
+                    break;
+                }
+                case 'tool_result': {
+                    const toolId = block.tool_use_id || '';
+                    let resultText = '';
+                    if (typeof block.content === 'string') {
+                        resultText = block.content;
+                    }
+                    else if (Array.isArray(block.content)) {
+                        resultText = block.content
+                            .filter(c => c.type === 'text')
+                            .map(c => c.text || '')
+                            .join('\n');
+                    }
+                    // Truncate long results
+                    if (resultText.length > 500) {
+                        resultText = resultText.slice(0, 500) + '... (truncated)';
+                    }
+                    if (resultText.trim()) {
+                        results.push({
+                            role: 'assistant',
+                            contentType: block.is_error ? 'tool_error' : 'tool_result',
+                            text: resultText.trim(),
+                            toolUseId: toolId,
+                            timestamp,
+                        });
+                    }
+                    pendingTools.delete(toolId);
+                    break;
+                }
+                case 'permission_request': {
+                    const permText = block.text || JSON.stringify(block);
+                    if (permText.trim()) {
+                        results.push({
+                            role: 'user',
+                            contentType: 'permission_request',
+                            text: permText.trim(),
+                            timestamp,
+                        });
+                    }
+                    break;
+                }
+            }
+        }
+    }
+    return results;
+}
+/** Issue #488: Sum token usage across a batch of raw JSONL entries. */
+export function extractTokenDelta(raw) {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheCreationTokens = 0;
+    let cacheReadTokens = 0;
+    for (const entry of raw) {
+        const u = entry.message?.usage;
+        if (!u)
+            continue;
+        inputTokens += u.input_tokens ?? 0;
+        outputTokens += u.output_tokens ?? 0;
+        cacheCreationTokens += u.cache_creation_input_tokens ?? 0;
+        cacheReadTokens += u.cache_read_input_tokens ?? 0;
+    }
+    return { inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens };
+}
+/** Read JSONL file from byte offset, return new entries + new offset. */
+export async function readNewEntries(filePath, fromOffset) {
+    // Issue #623: Use a single fd for stat + read to eliminate TOCTOU race.
+    const fd = await open(filePath, 'r');
+    try {
+        const fileStat = await fd.stat();
+        // File truncated (e.g. after /clear)
+        if (fromOffset > fileStat.size) {
+            return { entries: [], newOffset: 0, raw: [] };
+        }
+        if (fromOffset >= fileStat.size) {
+            return { entries: [], newOffset: fromOffset, raw: [] };
+        }
+        // Read from byte offset to end using createReadStream to avoid loading entire file
+        // Issue #222: Only read from offset forward, not the whole file
+        // Issue #259: If offset lands mid-entry, scan backwards to previous newline
+        // Issue #409: Use async I/O instead of readFileSync to avoid blocking the event loop
+        let effectiveOffset = fromOffset;
+        if (effectiveOffset > 0) {
+            const scanSize = 4096;
+            const scanStart = Math.max(0, effectiveOffset - scanSize);
+            const scanLen = effectiveOffset - scanStart;
+            const scanBuf = Buffer.alloc(scanLen);
+            await fd.read(scanBuf, 0, scanLen, scanStart);
+            let foundNewline = false;
+            for (let i = scanBuf.length - 1; i >= 0; i--) {
+                if (scanBuf[i] === 0x0a) { // '\n'
+                    effectiveOffset = scanStart + i + 1;
+                    foundNewline = true;
+                    break;
+                }
+            }
+            // Issue #836: If no newline found in the scan window, the line is
+            // longer than scanSize. Keep effectiveOffset as-is (fromOffset) —
+            // starting mid-line is handled by JSON.parse rejecting partial lines.
+            // Never fall back to offset 0, which causes O(n) re-reads.
+        }
+        const slicedContent = await new Promise((resolve, reject) => {
+            const chunks = [];
+            // Reuse the same fd — autoClose: false because we close it in the outer finally
+            const stream = createReadStream(filePath, { fd: fd.fd, start: effectiveOffset, autoClose: false });
+            stream.on('data', (chunk) => { if (typeof chunk !== 'string')
+                chunks.push(chunk); });
+            stream.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+            stream.on('error', reject);
+        });
+        const lines = slicedContent.split('\n');
+        const rawEntries = [];
+        for (const line of lines) {
+            const entry = parseLine(line);
+            if (entry) {
+                rawEntries.push(entry);
+            }
+        }
+        const parsed = parseEntries(rawEntries);
+        return { entries: parsed, newOffset: fileStat.size, raw: rawEntries };
+    }
+    finally {
+        await fd.close();
+    }
+}
+/** Check if a path exists (async). Issue #658: replaces sync existsSync. */
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Find the JSONL file for a session ID. */
+export async function findSessionFile(sessionId, claudeProjectsDir = DEFAULT_CLAUDE_PROJECTS_DIR) {
+    const projectsDir = claudeProjectsDir;
+    if (!(await pathExists(projectsDir)))
+        return null;
+    // Strategy 1: Direct glob across all project dirs
+    const dirs = await readdir(projectsDir, { withFileTypes: true });
+    for (const dir of dirs) {
+        if (!dir.isDirectory())
+            continue;
+        const jsonlPath = join(projectsDir, dir.name, `${sessionId}.jsonl`);
+        if (await pathExists(jsonlPath))
+            return jsonlPath;
+    }
+    // Strategy 2: Check sessions-index.json files
+    for (const dir of dirs) {
+        if (!dir.isDirectory())
+            continue;
+        const indexPath = join(projectsDir, dir.name, 'sessions-index.json');
+        if (await pathExists(indexPath)) {
+            try {
+                const indexRaw = await readFile(indexPath, 'utf-8');
+                const indexParsed = safeJsonParseSchema(indexRaw, sessionsIndexSchema, 'sessions-index.json');
+                if (!indexParsed.ok)
+                    continue;
+                const entries = indexParsed.data.entries || [];
+                for (const entry of entries) {
+                    if (entry.sessionId === sessionId && entry.fullPath && (await pathExists(entry.fullPath))) {
+                        return entry.fullPath;
+                    }
+                }
+            }
+            catch { /* skip bad index */ }
+        }
+    }
+    return null;
+}

package/dist/utils/circular-buffer.d.ts

@@ -0,0 +1,11 @@
+export declare class CircularBuffer<T> {
+    private readonly capacity;
+    private readonly items;
+    private head;
+    private count;
+    constructor(capacity: number);
+    push(item: T): void;
+    toArray(): T[];
+    clear(): void;
+    size(): number;
+}

package/dist/utils/circular-buffer.js

@@ -0,0 +1,37 @@
+export class CircularBuffer {
+    capacity;
+    items;
+    head = 0;
+    count = 0;
+    constructor(capacity) {
+        this.capacity = capacity;
+        if (!Number.isInteger(capacity) || capacity <= 0) {
+            throw new Error(`CircularBuffer capacity must be a positive integer, got: ${capacity}`);
+        }
+        this.items = new Array(capacity);
+    }
+    push(item) {
+        this.items[this.head] = item;
+        this.head = (this.head + 1) % this.capacity;
+        if (this.count < this.capacity) {
+            this.count++;
+        }
+    }
+    toArray() {
+        if (this.count === 0) {
+            return [];
+        }
+        if (this.count < this.capacity) {
+            return this.items.slice(0, this.count);
+        }
+        return [...this.items.slice(this.head), ...this.items.slice(0, this.head)];
+    }
+    clear() {
+        this.items.fill(undefined);
+        this.head = 0;
+        this.count = 0;
+    }
+    size() {
+        return this.count;
+    }
+}

package/dist/utils/redact-headers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * redact-headers.ts — Redact sensitive header values for safe logging.
+ *
+ * Issue #582: Prevent webhook custom headers (Authorization, Cookie, etc.)
+ * from leaking into error logs on delivery failures.
+ */
+/** Return a copy of `headers` with sensitive values replaced. */
+export declare function redactHeaders(headers: Record<string, string>): Record<string, string>;
+/**
+ * Scrub any sensitive header *values* from arbitrary text.
+ * If a fetch error message happens to include a header value, this removes it.
+ */
+export declare function redactSecretsFromText(text: string, headers: Record<string, string> | undefined): string;

package/dist/utils/redact-headers.js

@@ -0,0 +1,54 @@
+/**
+ * redact-headers.ts — Redact sensitive header values for safe logging.
+ *
+ * Issue #582: Prevent webhook custom headers (Authorization, Cookie, etc.)
+ * from leaking into error logs on delivery failures.
+ */
+/** Header names whose values should be treated as secrets. Case-insensitive. */
+const SENSITIVE_HEADER_NAMES = new Set([
+    'authorization',
+    'cookie',
+    'set-cookie',
+    'x-api-key',
+    'x-auth-token',
+    'api-key',
+    'apikey',
+    'proxy-authorization',
+    'x-csrf-token',
+    'www-authenticate',
+    'proxy-authenticate',
+]);
+function isSensitive(headerName) {
+    return SENSITIVE_HEADER_NAMES.has(headerName.toLowerCase());
+}
+function redactValue(value) {
+    if (value.length <= 8)
+        return '[REDACTED]';
+    return `${value.slice(0, 4)}...[REDACTED]`;
+}
+/** Return a copy of `headers` with sensitive values replaced. */
+export function redactHeaders(headers) {
+    const result = {};
+    for (const [name, value] of Object.entries(headers)) {
+        result[name] = isSensitive(name) ? redactValue(value) : value;
+    }
+    return result;
+}
+/**
+ * Scrub any sensitive header *values* from arbitrary text.
+ * If a fetch error message happens to include a header value, this removes it.
+ */
+export function redactSecretsFromText(text, headers) {
+    if (!headers)
+        return text;
+    let result = text;
+    for (const [name, value] of Object.entries(headers)) {
+        if (!isSensitive(name) || !value)
+            continue;
+        // Skip very short values — too many false positives
+        if (value.length < 4)
+            continue;
+        result = result.replaceAll(value, '[REDACTED]');
+    }
+    return result;
+}