aegis-bridge 0.1.0

package/dist/path-utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * path-utils.ts — path helpers shared across session/tmux logic.
+ */
+/**
+ * Compute the Claude project hash folder from a workDir path.
+ *
+ * Examples:
+ * - /home/user/project -> -home-user-project
+ * - D:\\Users\\me\\project -> -d-Users-me-project
+ */
+export declare function computeProjectHash(workDir: string): string;

package/dist/path-utils.js

@@ -0,0 +1,21 @@
+/**
+ * path-utils.ts — path helpers shared across session/tmux logic.
+ */
+/**
+ * Compute the Claude project hash folder from a workDir path.
+ *
+ * Examples:
+ * - /home/user/project -> -home-user-project
+ * - D:\\Users\\me\\project -> -d-Users-me-project
+ */
+export function computeProjectHash(workDir) {
+    const normalized = workDir.replace(/\\/g, '/').trim();
+    const withLowerDrive = normalized.replace(/^[A-Za-z]:/, (m) => `${m[0].toLowerCase()}`);
+    const segments = withLowerDrive
+        .split('/')
+        .filter(Boolean)
+        .map((segment) => segment.replace(/:/g, '').replace(/\s+/g, '-'));
+    if (segments.length === 0)
+        return '-';
+    return `-${segments.join('-')}`;
+}

package/dist/permission-evaluator.d.ts

@@ -0,0 +1,10 @@
+import type { PermissionProfile } from './validation.js';
+export interface PermissionEvaluationInput {
+    toolName: string;
+    toolInput?: Record<string, unknown>;
+}
+export interface PermissionEvaluationResult {
+    behavior: 'allow' | 'deny' | 'ask';
+    reason: string;
+}
+export declare function evaluatePermissionProfile(profile: PermissionProfile, input: PermissionEvaluationInput): PermissionEvaluationResult;

package/dist/permission-evaluator.js

@@ -0,0 +1,48 @@
+function globToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`, 'i');
+}
+function extractCandidatePaths(toolInput) {
+    if (!toolInput)
+        return [];
+    const values = [toolInput.path, toolInput.file_path, toolInput.target, ...(Array.isArray(toolInput.paths) ? toolInput.paths : [])];
+    return values.filter((v) => typeof v === 'string');
+}
+function extractContentSize(toolInput) {
+    const content = toolInput?.content;
+    return typeof content === 'string' ? content.length : null;
+}
+function isLikelyWriteTool(toolName) {
+    return /write|edit|delete|rename|move|create/i.test(toolName);
+}
+export function evaluatePermissionProfile(profile, input) {
+    for (const rule of profile.rules) {
+        if (rule.tool !== input.toolName)
+            continue;
+        if (rule.pattern) {
+            const candidate = typeof input.toolInput?.command === 'string'
+                ? input.toolInput.command
+                : JSON.stringify(input.toolInput ?? {});
+            if (!globToRegExp(rule.pattern).test(candidate))
+                continue;
+        }
+        if (rule.constraints?.readOnly && isLikelyWriteTool(input.toolName)) {
+            return { behavior: 'deny', reason: `Denied by readOnly constraint for ${input.toolName}` };
+        }
+        if (rule.constraints?.paths && rule.constraints.paths.length > 0) {
+            const paths = extractCandidatePaths(input.toolInput);
+            const allowed = paths.every((candidate) => rule.constraints.paths.some((prefix) => candidate.startsWith(prefix)));
+            if (!allowed) {
+                return { behavior: 'deny', reason: `Denied by path constraint for ${input.toolName}` };
+            }
+        }
+        if (rule.constraints?.maxFileSize) {
+            const size = extractContentSize(input.toolInput);
+            if (size !== null && size > rule.constraints.maxFileSize) {
+                return { behavior: 'deny', reason: `Denied by maxFileSize constraint for ${input.toolName}` };
+            }
+        }
+        return { behavior: rule.behavior, reason: `Matched rule for ${input.toolName}` };
+    }
+    return { behavior: profile.defaultBehavior, reason: 'No matching permission rule' };
+}

package/dist/permission-guard.d.ts

@@ -0,0 +1,51 @@
+/**
+ * permission-guard.ts — Guard against settings overriding CLI permission mode.
+ *
+ * Problem: Claude Code checks settings in 3 locations (priority order):
+ *   1. ~/.claude/settings.json (user-level)
+ *   2. <project>/.claude/settings.json (project-level, committed)
+ *   3. <project>/.claude/settings.local.json (project-level, local)
+ *
+ * Any of these can set `permissions.defaultMode: "bypassPermissions"` which
+ * OVERRIDES the CLI `--permission-mode default` flag. When Aegis spawns a
+ * session with autoApprove: false, the user expects permission prompts — but
+ * the settings silently bypass them.
+ *
+ * Fix: Before launching CC, if autoApprove is false, we neutralize any
+ * `bypassPermissions` in ALL 3 settings files by backing them up and patching
+ * the permission mode. On session cleanup we restore them.
+ *
+ * Issue #102 safety: Backups are stored in ~/.aegis/permission-backups/
+ * instead of the project directory to prevent accidental commit of secrets.
+ */
+/** Location 3: project-level local settings */
+export declare function settingsPath(workDir: string): string;
+/** Location 2: project-level committed settings */
+export declare function projectSettingsPath(workDir: string): string;
+/** Location 1: user-level settings. Accepts optional homeDir for test isolation. */
+export declare function userSettingsPath(homeDir?: string): string;
+/** Backup directory for a given workDir. Accepts optional homeDir for test isolation. */
+export declare function backupDirForWorkDir(workDir: string, homeDir?: string): string;
+/** Get backup path for settings.local.json. Accepts optional homeDir for test isolation. */
+export declare function backupPath(workDir: string, homeDir?: string): string;
+/**
+ * Check all 3 CC settings locations for bypassPermissions. Back up and patch
+ * any that have it. Returns true if ANY file was patched.
+ *
+ * @param homeDir - Override home directory (for test isolation). Defaults to os.homedir().
+ */
+export declare function neutralizeBypassPermissions(workDir: string, targetMode?: string, homeDir?: string): Promise<boolean>;
+/**
+ * Restore all 3 settings files from backups.
+ * Checks new backup locations first, then legacy location for backward compat.
+ *
+ * @param homeDir - Override home directory (for test isolation). Defaults to os.homedir().
+ */
+export declare function restoreSettings(workDir: string, homeDir?: string): Promise<void>;
+/**
+ * Clean up any orphaned backups (e.g. from a crash).
+ * Restores all 3 settings files from their backups.
+ *
+ * @param homeDir - Override home directory (for test isolation). Defaults to os.homedir().
+ */
+export declare function cleanOrphanedBackup(workDir: string, homeDir?: string): Promise<void>;

package/dist/permission-guard.js

@@ -0,0 +1,196 @@
+/**
+ * permission-guard.ts — Guard against settings overriding CLI permission mode.
+ *
+ * Problem: Claude Code checks settings in 3 locations (priority order):
+ *   1. ~/.claude/settings.json (user-level)
+ *   2. <project>/.claude/settings.json (project-level, committed)
+ *   3. <project>/.claude/settings.local.json (project-level, local)
+ *
+ * Any of these can set `permissions.defaultMode: "bypassPermissions"` which
+ * OVERRIDES the CLI `--permission-mode default` flag. When Aegis spawns a
+ * session with autoApprove: false, the user expects permission prompts — but
+ * the settings silently bypass them.
+ *
+ * Fix: Before launching CC, if autoApprove is false, we neutralize any
+ * `bypassPermissions` in ALL 3 settings files by backing them up and patching
+ * the permission mode. On session cleanup we restore them.
+ *
+ * Issue #102 safety: Backups are stored in ~/.aegis/permission-backups/
+ * instead of the project directory to prevent accidental commit of secrets.
+ */
+import { readFile, writeFile, rename, unlink } from 'node:fs/promises';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { ccSettingsSchema } from './validation.js';
+const SETTINGS_DIR = '.claude';
+const LOCAL_SETTINGS_FILE = 'settings.local.json';
+const PROJECT_SETTINGS_FILE = 'settings.json';
+/** Hash a workDir path to create a safe, unique backup directory name. */
+function workDirHash(workDir) {
+    return createHash('sha256').update(workDir).digest('hex').slice(0, 16);
+}
+// ─── Path helpers ───
+/** Location 3: project-level local settings */
+export function settingsPath(workDir) {
+    return join(workDir, SETTINGS_DIR, LOCAL_SETTINGS_FILE);
+}
+/** Location 2: project-level committed settings */
+export function projectSettingsPath(workDir) {
+    return join(workDir, SETTINGS_DIR, PROJECT_SETTINGS_FILE);
+}
+/** Location 1: user-level settings. Accepts optional homeDir for test isolation. */
+export function userSettingsPath(homeDir) {
+    return join(homeDir ?? homedir(), SETTINGS_DIR, PROJECT_SETTINGS_FILE);
+}
+/** Backup directory for a given workDir. Accepts optional homeDir for test isolation. */
+export function backupDirForWorkDir(workDir, homeDir) {
+    const aegisDir = join(homeDir ?? homedir(), '.aegis');
+    return join(aegisDir, 'permission-backups', workDirHash(workDir));
+}
+/** Get backup path for settings.local.json. Accepts optional homeDir for test isolation. */
+export function backupPath(workDir, homeDir) {
+    return join(backupDirForWorkDir(workDir, homeDir), LOCAL_SETTINGS_FILE);
+}
+/** Legacy backup path (in project dir) — for migration/cleanup. */
+function legacyBackupPath(workDir) {
+    return settingsPath(workDir) + '.aegis-backup';
+}
+/** User-level backup directory. */
+function userBackupDir(homeDir) {
+    return join(homeDir, '.aegis', 'permission-backups', '_user_');
+}
+/** All settings locations that could contain bypassPermissions. */
+function getAllSettingsLocations(workDir, homeDir) {
+    return [
+        // Location 1: user-level
+        { filePath: userSettingsPath(homeDir), backupPath: join(userBackupDir(homeDir), PROJECT_SETTINGS_FILE) },
+        // Location 2: project-level committed
+        { filePath: projectSettingsPath(workDir), backupPath: join(backupDirForWorkDir(workDir, homeDir), PROJECT_SETTINGS_FILE) },
+        // Location 3: project-level local
+        { filePath: settingsPath(workDir), backupPath: backupPath(workDir, homeDir) },
+    ];
+}
+/**
+ * Check a single settings file for bypassPermissions, back it up, and patch it.
+ * Returns true if the file was patched.
+ */
+async function neutralizeOneFile(filePath, bpPath, targetMode) {
+    if (!existsSync(filePath))
+        return false;
+    try {
+        const raw = await readFile(filePath, 'utf-8');
+        const settingsParsed = ccSettingsSchema.safeParse(JSON.parse(raw));
+        if (!settingsParsed.success)
+            return false;
+        const settings = settingsParsed.data;
+        const mode = settings?.permissions?.defaultMode;
+        if (mode !== 'bypassPermissions')
+            return false;
+        // Back up
+        mkdirSync(join(bpPath, '..'), { recursive: true });
+        await writeFile(bpPath, raw);
+        // Patch
+        if (!settings.permissions)
+            settings.permissions = {};
+        settings.permissions.defaultMode = targetMode;
+        await writeFile(filePath, JSON.stringify(settings, null, 2) + '\n');
+        console.log(`Permission guard: neutralized bypassPermissions in ${filePath} (backup: ${bpPath})`);
+        return true;
+    }
+    catch (e) {
+        console.error(`Permission guard: failed to neutralize ${filePath}: ${e.message}`);
+        return false;
+    }
+}
+/**
+ * Check all 3 CC settings locations for bypassPermissions. Back up and patch
+ * any that have it. Returns true if ANY file was patched.
+ *
+ * @param homeDir - Override home directory (for test isolation). Defaults to os.homedir().
+ */
+export async function neutralizeBypassPermissions(workDir, targetMode = 'default', homeDir) {
+    const locations = getAllSettingsLocations(workDir, homeDir ?? homedir());
+    let anyPatched = false;
+    for (const loc of locations) {
+        const patched = await neutralizeOneFile(loc.filePath, loc.backupPath, targetMode);
+        if (patched)
+            anyPatched = true;
+    }
+    return anyPatched;
+}
+/**
+ * Restore a single settings file from its backup.
+ */
+async function restoreOneFile(filePath, bpPath) {
+    if (!existsSync(bpPath))
+        return false;
+    try {
+        const raw = await readFile(bpPath, 'utf-8');
+        await writeFile(filePath, raw);
+        await unlink(bpPath);
+        console.log(`Permission guard: restored ${filePath} from backup`);
+        return true;
+    }
+    catch (e) {
+        console.error(`Permission guard: failed to restore from ${bpPath}: ${e.message}`);
+        return false;
+    }
+}
+/**
+ * Restore all 3 settings files from backups.
+ * Checks new backup locations first, then legacy location for backward compat.
+ *
+ * @param homeDir - Override home directory (for test isolation). Defaults to os.homedir().
+ */
+export async function restoreSettings(workDir, homeDir) {
+    const locations = getAllSettingsLocations(workDir, homeDir ?? homedir());
+    for (const loc of locations) {
+        await restoreOneFile(loc.filePath, loc.backupPath);
+    }
+    // Legacy fallback for settings.local.json only (in project dir)
+    const legacy = legacyBackupPath(workDir);
+    if (existsSync(legacy)) {
+        try {
+            await rename(legacy, settingsPath(workDir));
+            console.log(`Permission guard: restored ${settingsPath(workDir)} from legacy backup`);
+        }
+        catch (e) {
+            console.error(`Permission guard: failed to restore from legacy ${legacy}: ${e.message}`);
+        }
+    }
+}
+/**
+ * Clean up any orphaned backups (e.g. from a crash).
+ * Restores all 3 settings files from their backups.
+ *
+ * @param homeDir - Override home directory (for test isolation). Defaults to os.homedir().
+ */
+export async function cleanOrphanedBackup(workDir, homeDir) {
+    const locations = getAllSettingsLocations(workDir, homeDir ?? homedir());
+    for (const loc of locations) {
+        if (!existsSync(loc.backupPath))
+            continue;
+        try {
+            const raw = await readFile(loc.backupPath, 'utf-8');
+            await writeFile(loc.filePath, raw);
+            await unlink(loc.backupPath);
+            console.log(`Permission guard: cleaned orphaned backup for ${loc.filePath}`);
+        }
+        catch (e) {
+            console.error(`Permission guard: failed to clean orphaned backup: ${e.message}`);
+        }
+    }
+    // Clean legacy backup
+    const legacy = legacyBackupPath(workDir);
+    if (existsSync(legacy)) {
+        try {
+            await rename(legacy, settingsPath(workDir));
+            console.log(`Permission guard: cleaned legacy orphaned backup in ${workDir}`);
+        }
+        catch (e) {
+            console.error(`Permission guard: failed to clean legacy orphaned backup: ${e.message}`);
+        }
+    }
+}

package/dist/permission-request-manager.d.ts

@@ -0,0 +1,12 @@
+export type PermissionDecision = 'allow' | 'deny';
+export declare class PermissionRequestManager {
+    private pendingPermissions;
+    waitForPermissionDecision(sessionId: string, timeoutMs?: number, toolName?: string, prompt?: string): Promise<PermissionDecision>;
+    hasPendingPermission(sessionId: string): boolean;
+    getPendingPermissionInfo(sessionId: string): {
+        toolName?: string;
+        prompt?: string;
+    } | null;
+    resolvePendingPermission(sessionId: string, decision: PermissionDecision): boolean;
+    cleanupPendingPermission(sessionId: string): void;
+}

package/dist/permission-request-manager.js

@@ -0,0 +1,36 @@
+export class PermissionRequestManager {
+    pendingPermissions = new Map();
+    waitForPermissionDecision(sessionId, timeoutMs = 10_000, toolName, prompt) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pendingPermissions.delete(sessionId);
+                console.log(`Hooks: PermissionRequest timeout for session ${sessionId} - auto-rejecting`);
+                resolve('deny');
+            }, timeoutMs);
+            this.pendingPermissions.set(sessionId, { resolve, timer, toolName, prompt });
+        });
+    }
+    hasPendingPermission(sessionId) {
+        return this.pendingPermissions.has(sessionId);
+    }
+    getPendingPermissionInfo(sessionId) {
+        const pending = this.pendingPermissions.get(sessionId);
+        return pending ? { toolName: pending.toolName, prompt: pending.prompt } : null;
+    }
+    resolvePendingPermission(sessionId, decision) {
+        const pending = this.pendingPermissions.get(sessionId);
+        if (!pending)
+            return false;
+        clearTimeout(pending.timer);
+        this.pendingPermissions.delete(sessionId);
+        pending.resolve(decision);
+        return true;
+    }
+    cleanupPendingPermission(sessionId) {
+        const pending = this.pendingPermissions.get(sessionId);
+        if (pending) {
+            clearTimeout(pending.timer);
+            this.pendingPermissions.delete(sessionId);
+        }
+    }
+}

package/dist/permission-routes.d.ts

@@ -0,0 +1,7 @@
+import type { FastifyInstance } from 'fastify';
+import type { SessionManager } from './session.js';
+import type { MetricsCollector } from './metrics.js';
+type PermissionSessions = Pick<SessionManager, 'approve' | 'reject' | 'getLatencyMetrics'>;
+type PermissionMetrics = Pick<MetricsCollector, 'recordPermissionResponse'>;
+export declare function registerPermissionRoutes(app: FastifyInstance, sessions: PermissionSessions, metrics: PermissionMetrics): void;
+export {};

package/dist/permission-routes.js

@@ -0,0 +1,28 @@
+function createPermissionHandler(action, sessions, metrics) {
+    return async (req, reply) => {
+        try {
+            if (action === 'approve') {
+                await sessions.approve(req.params.id);
+            }
+            else {
+                await sessions.reject(req.params.id);
+            }
+            // Issue #87: Record permission response latency.
+            const lat = sessions.getLatencyMetrics(req.params.id);
+            if (lat !== null && lat.permission_response_ms !== null) {
+                metrics.recordPermissionResponse(req.params.id, lat.permission_response_ms);
+            }
+            return { ok: true };
+        }
+        catch (e) {
+            return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+        }
+    };
+}
+export function registerPermissionRoutes(app, sessions, metrics) {
+    for (const action of ['approve', 'reject']) {
+        const handler = createPermissionHandler(action, sessions, metrics);
+        app.post(`/v1/sessions/:id/${action}`, handler);
+        app.post(`/sessions/:id/${action}`, handler);
+    }
+}

package/dist/pipeline.d.ts

@@ -0,0 +1,97 @@
+/**
+ * pipeline.ts — Batch create and pipeline orchestration.
+ *
+ * Issue #36: Create multiple sessions in parallel, or define
+ * sequential pipelines with stage dependencies.
+ */
+import { type SessionManager } from './session.js';
+import { type SessionEventBus } from './events.js';
+export interface BatchSessionSpec {
+    name?: string;
+    workDir: string;
+    prompt?: string;
+    permissionMode?: string;
+    /** @deprecated Use permissionMode instead. */
+    autoApprove?: boolean;
+    stallThresholdMs?: number;
+}
+export interface BatchResult {
+    sessions: Array<{
+        id: string;
+        name: string;
+        promptDelivery?: {
+            delivered: boolean;
+            attempts: number;
+        };
+    }>;
+    created: number;
+    failed: number;
+    errors: string[];
+}
+export interface PipelineStage {
+    name: string;
+    workDir?: string;
+    prompt: string;
+    dependsOn?: string[];
+    permissionMode?: string;
+    /** @deprecated Use permissionMode instead. */
+    autoApprove?: boolean;
+}
+export interface PipelineConfig {
+    name: string;
+    workDir: string;
+    stages: PipelineStage[];
+}
+export type PipelineStageStatus = 'pending' | 'running' | 'completed' | 'failed';
+export interface PipelineState {
+    id: string;
+    name: string;
+    currentStage: 'plan' | 'execute' | 'verify' | 'fix' | 'submit' | 'done';
+    status: 'running' | 'completed' | 'failed';
+    retryCount: number;
+    maxRetries: number;
+    stageHistory: Array<{
+        stage: string;
+        enteredAt: number;
+        exitedAt?: number;
+        output?: unknown;
+    }>;
+    stages: Array<{
+        name: string;
+        status: PipelineStageStatus;
+        sessionId?: string;
+        dependsOn: string[];
+        startedAt?: number;
+        completedAt?: number;
+        error?: string;
+    }>;
+    createdAt: number;
+}
+export declare class PipelineManager {
+    private sessions;
+    private eventBus?;
+    private static readonly PIPELINE_RETRY_MAX_ATTEMPTS;
+    private static readonly PIPELINE_FIX_MAX_RETRIES;
+    private pipelines;
+    private pipelineConfigs;
+    private pollInterval;
+    private cleanupTimers;
+    constructor(sessions: SessionManager, eventBus?: SessionEventBus | undefined);
+    /** Create multiple sessions in parallel. */
+    batchCreate(specs: BatchSessionSpec[]): Promise<BatchResult>;
+    /** Create a pipeline with stage dependencies. */
+    createPipeline(config: PipelineConfig): Promise<PipelineState>;
+    /** Get pipeline state. */
+    getPipeline(id: string): PipelineState | null;
+    /** List all pipelines. */
+    listPipelines(): PipelineState[];
+    /** Advance a pipeline: start stages whose dependencies are met. */
+    private advancePipeline;
+    /** Poll running pipelines and advance stages. */
+    private pollPipelines;
+    private transitionPipelineStage;
+    /** Detect circular dependencies. Throws if found. */
+    private detectCycles;
+    /** Clean up. */
+    destroy(): void;
+}