aegis-bridge 0.1.0

package/dist/jsonl-watcher.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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, type TokenUsageDelta } from './transcript.js';
+export interface JsonlWatcherEvent {
+    sessionId: string;
+    messages: ParsedEntry[];
+    newOffset: number;
+    /** True if the file was truncated (e.g. after /clear). */
+    truncated: boolean;
+    /** Issue #488: Aggregated token usage delta from this batch of entries. */
+    tokenUsageDelta: TokenUsageDelta;
+}
+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;
+}

package/dist/jsonl-watcher.js

@@ -0,0 +1,166 @@
+/**
+ * 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 { watch } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { readNewEntries, extractTokenDelta } from './transcript.js';
+const DEFAULT_CONFIG = {
+    debounceMs: 100,
+};
+/**
+ * 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 class JsonlWatcher {
+    entries = new Map();
+    listeners = new Array();
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /** Register a callback for new entries. */
+    onEntries(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx >= 0)
+                this.listeners.splice(idx, 1);
+        };
+    }
+    /** Start watching a JSONL file for a session.
+     *  @param initialOffset - byte offset to start reading from (usually 0 or current session.monitorOffset).
+     */
+    watch(sessionId, jsonlPath, initialOffset) {
+        // Issue #846: Clear stale timer before re-watching to prevent
+        // old timer closures from operating on stale entry data.
+        if (this.entries.has(sessionId)) {
+            const oldEntry = this.entries.get(sessionId);
+            if (oldEntry.debounceTimer) {
+                clearTimeout(oldEntry.debounceTimer);
+                oldEntry.debounceTimer = null;
+            }
+            oldEntry.fsWatcher.close();
+            this.entries.delete(sessionId);
+        }
+        if (!existsSync(jsonlPath))
+            return;
+        const fsWatcher = watch(jsonlPath, (eventType) => {
+            // 'rename' can mean file was deleted or replaced — check if it still exists
+            if (eventType === 'rename') {
+                if (!existsSync(jsonlPath)) {
+                    // File deleted — session likely ended, stop watching
+                    this.unwatch(sessionId);
+                    return;
+                }
+                // File was replaced (e.g. rotated) — re-read from current offset
+                this.scheduleRead(sessionId);
+                return;
+            }
+            // 'change' — new data written
+            this.scheduleRead(sessionId);
+        });
+        fsWatcher.on('error', (err) => {
+            console.error(`JsonlWatcher: error watching ${jsonlPath}:`, err.message);
+            // Stop watching on persistent errors
+            this.unwatch(sessionId);
+        });
+        this.entries.set(sessionId, {
+            sessionId,
+            jsonlPath,
+            fsWatcher,
+            debounceTimer: null,
+            offset: initialOffset,
+        });
+    }
+    /** Stop watching a session's JSONL file. */
+    unwatch(sessionId) {
+        const entry = this.entries.get(sessionId);
+        if (!entry)
+            return;
+        if (entry.debounceTimer) {
+            clearTimeout(entry.debounceTimer);
+        }
+        entry.fsWatcher.close();
+        this.entries.delete(sessionId);
+    }
+    /** Update the offset for a session (e.g. after manual read during discovery). */
+    setOffset(sessionId, offset) {
+        const entry = this.entries.get(sessionId);
+        if (entry) {
+            entry.offset = offset;
+        }
+    }
+    /** Check if a session is being watched. */
+    isWatching(sessionId) {
+        return this.entries.has(sessionId);
+    }
+    /** Get the current offset for a watched session. */
+    getOffset(sessionId) {
+        return this.entries.get(sessionId)?.offset;
+    }
+    /** Stop all watchers and clean up. */
+    destroy() {
+        for (const sessionId of this.entries.keys()) {
+            this.unwatch(sessionId);
+        }
+        this.listeners.length = 0;
+    }
+    /** Schedule a debounced read for a session. */
+    scheduleRead(sessionId) {
+        const entry = this.entries.get(sessionId);
+        if (!entry)
+            return;
+        if (entry.debounceTimer) {
+            clearTimeout(entry.debounceTimer);
+        }
+        entry.debounceTimer = setTimeout(() => {
+            entry.debounceTimer = null;
+            void this.readAndEmit(entry);
+        }, this.config.debounceMs);
+    }
+    /** Read new bytes from the JSONL file and emit entries. */
+    async readAndEmit(entry) {
+        // Session may have been removed during debounce
+        if (!this.entries.has(entry.sessionId))
+            return;
+        if (!existsSync(entry.jsonlPath)) {
+            this.unwatch(entry.sessionId);
+            return;
+        }
+        try {
+            const previousOffset = entry.offset;
+            const result = await readNewEntries(entry.jsonlPath, previousOffset);
+            entry.offset = result.newOffset;
+            if (result.entries.length > 0 || result.newOffset < previousOffset) {
+                // Detect truncation: newOffset went backwards
+                const truncated = result.newOffset < previousOffset;
+                // Emit to all listeners
+                const event = {
+                    sessionId: entry.sessionId,
+                    messages: result.entries,
+                    newOffset: result.newOffset,
+                    truncated,
+                    tokenUsageDelta: extractTokenDelta(result.raw),
+                };
+                for (const listener of this.listeners) {
+                    listener(event);
+                }
+            }
+        }
+        catch {
+            // File may be temporarily unavailable — ignore
+        }
+    }
+}

package/dist/logger.d.ts

@@ -0,0 +1,35 @@
+/**
+ * logger.ts - structured logger that also emits sanitized diagnostics events.
+ */
+import { type DiagnosticsBus, type DiagnosticsLevel } from './diagnostics.js';
+export interface LogContext {
+    component: string;
+    operation: string;
+    sessionId?: string;
+    errorCode?: string;
+    attributes?: Record<string, unknown>;
+}
+export interface StructuredLogRecord {
+    timestamp: string;
+    level: DiagnosticsLevel;
+    component: string;
+    operation: string;
+    sessionId?: string;
+    errorCode?: string;
+    attributes: Record<string, unknown>;
+}
+export interface StructuredLogSink {
+    info?: (record: StructuredLogRecord) => void;
+    warn?: (record: StructuredLogRecord) => void;
+    error?: (record: StructuredLogRecord) => void;
+}
+export declare function setStructuredLogSink(nextSink: StructuredLogSink): void;
+export declare class StructuredLogger {
+    private readonly bus;
+    constructor(bus?: DiagnosticsBus);
+    info(ctx: LogContext): void;
+    warn(ctx: LogContext): void;
+    error(ctx: LogContext): void;
+    private log;
+}
+export declare const logger: StructuredLogger;

package/dist/logger.js

@@ -0,0 +1,65 @@
+/**
+ * logger.ts - structured logger that also emits sanitized diagnostics events.
+ */
+import { diagnosticsBus, sanitizeDiagnosticsAttributes, } from './diagnostics.js';
+const defaultSink = {
+    info: (record) => console.log(JSON.stringify(record)),
+    warn: (record) => console.warn(JSON.stringify(record)),
+    error: (record) => console.error(JSON.stringify(record)),
+};
+let sink = defaultSink;
+export function setStructuredLogSink(nextSink) {
+    sink = {
+        info: nextSink.info ?? defaultSink.info,
+        warn: nextSink.warn ?? defaultSink.warn,
+        error: nextSink.error ?? defaultSink.error,
+    };
+}
+export class StructuredLogger {
+    bus;
+    constructor(bus = diagnosticsBus) {
+        this.bus = bus;
+    }
+    info(ctx) {
+        this.log('info', ctx);
+    }
+    warn(ctx) {
+        this.log('warn', ctx);
+    }
+    error(ctx) {
+        this.log('error', ctx);
+    }
+    log(level, ctx) {
+        const timestamp = new Date().toISOString();
+        const attributes = sanitizeDiagnosticsAttributes(ctx.attributes);
+        const record = {
+            timestamp,
+            level,
+            component: ctx.component,
+            operation: ctx.operation,
+            sessionId: ctx.sessionId,
+            errorCode: ctx.errorCode,
+            attributes,
+        };
+        if (level === 'error') {
+            sink.error?.(record);
+        }
+        else if (level === 'warn') {
+            sink.warn?.(record);
+        }
+        else {
+            sink.info?.(record);
+        }
+        this.bus.emit({
+            event: `${ctx.component}.${ctx.operation}`,
+            level,
+            component: ctx.component,
+            operation: ctx.operation,
+            sessionId: ctx.sessionId,
+            errorCode: ctx.errorCode,
+            timestamp,
+            attributes,
+        });
+    }
+}
+export const logger = new StructuredLogger();

package/dist/mcp-server.d.ts

@@ -0,0 +1,123 @@
+/**
+ * mcp-server.ts — MCP server mode for Aegis.
+ *
+ * Exposes Aegis session orchestration as MCP tools via stdio transport.
+ * CC sessions can natively discover and communicate with sibling sessions.
+ *
+ * Usage:
+ *   aegis-bridge mcp                    # default port 9100
+ *   aegis-bridge mcp --port 3000        # custom port
+ *   claude mcp add --scope user aegis -- npx aegis-bridge mcp
+ *
+ * Issue #48: https://github.com/OneStepAt4time/aegis/issues/48
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type SessionInfo } from './session.js';
+import { type SessionMetrics, type SessionLatency, type SessionLatencySummary } from './metrics.js';
+import { type PipelineState, type BatchResult } from './pipeline.js';
+interface ServerHealthResponse {
+    status: string;
+    version: string;
+    platform: NodeJS.Platform;
+    uptime: number;
+    sessions: {
+        active: number;
+        total: number;
+    };
+    tmux: {
+        healthy: boolean;
+        [key: string]: unknown;
+    };
+    timestamp: string;
+}
+interface CreateSessionResponse {
+    id: string;
+    windowName: string;
+    workDir: string;
+    status: string;
+    promptDelivery?: {
+        delivered: boolean;
+        attempts: number;
+    };
+    reused?: boolean;
+    [key: string]: unknown;
+}
+interface SendMessageResponse {
+    ok: boolean;
+    delivered: boolean;
+    attempts: number;
+}
+interface OkResponse {
+    ok: boolean;
+}
+interface CapturePaneResponse {
+    pane: string;
+}
+interface SessionLatencyResponse {
+    sessionId: string;
+    realtime: SessionLatency | null;
+    aggregated: SessionLatencySummary | null;
+}
+interface MemoryEntryResponse {
+    entry: {
+        key: string;
+        value: string;
+        namespace: string;
+        created_at: number;
+        updated_at: number;
+        expires_at?: number;
+    };
+}
+export declare class AegisClient {
+    private baseUrl;
+    private authToken?;
+    constructor(baseUrl: string, authToken?: string | undefined);
+    private validateSessionId;
+    private request;
+    listSessions(filter?: {
+        status?: string;
+        workDir?: string;
+    }): Promise<SessionInfo[]>;
+    getSession(id: string): Promise<Record<string, unknown>>;
+    getHealth(id: string): Promise<Record<string, unknown>>;
+    getTranscript(id: string): Promise<Record<string, unknown>>;
+    sendMessage(id: string, text: string): Promise<SendMessageResponse>;
+    createSession(opts: {
+        workDir: string;
+        name?: string;
+        prompt?: string;
+    }): Promise<CreateSessionResponse>;
+    killSession(id: string): Promise<OkResponse>;
+    approvePermission(id: string): Promise<OkResponse>;
+    rejectPermission(id: string): Promise<OkResponse>;
+    getServerHealth(): Promise<ServerHealthResponse>;
+    escapeSession(id: string): Promise<OkResponse>;
+    interruptSession(id: string): Promise<OkResponse>;
+    capturePane(id: string): Promise<CapturePaneResponse>;
+    getSessionMetrics(id: string): Promise<SessionMetrics>;
+    getSessionSummary(id: string): Promise<Record<string, unknown>>;
+    sendBash(id: string, command: string): Promise<OkResponse>;
+    sendCommand(id: string, command: string): Promise<OkResponse>;
+    getSessionLatency(id: string): Promise<SessionLatencyResponse>;
+    batchCreateSessions(sessions: Array<{
+        workDir: string;
+        name?: string;
+        prompt?: string;
+    }>): Promise<BatchResult>;
+    listPipelines(): Promise<PipelineState[]>;
+    createPipeline(config: {
+        name: string;
+        workDir: string;
+        steps: Array<{
+            name?: string;
+            prompt: string;
+        }>;
+    }): Promise<PipelineState>;
+    getSwarm(): Promise<Record<string, unknown>>;
+    setMemory(key: string, value: string, ttlSeconds?: number): Promise<MemoryEntryResponse>;
+    getMemory(key: string): Promise<MemoryEntryResponse>;
+    deleteMemory(key: string): Promise<OkResponse>;
+}
+export declare function createMcpServer(aegisPort: number, authToken?: string): McpServer;
+export declare function startMcpServer(port: number, authToken?: string): Promise<void>;
+export {};