crewly 1.13.0 → 1.14.0

package/dist/cli/backend/src/services/session/session-state-persistence.js

@@ -0,0 +1,407 @@
+/**
+ * Session State Persistence Module
+ *
+ * Saves session metadata on shutdown and restores sessions on startup.
+ * This compensates for PTY sessions not persisting like tmux sessions do.
+ *
+ * @module session-state-persistence
+ */
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { LoggerService } from '../core/logger.service.js';
+import { atomicWriteJson, safeReadJson } from '../../utils/file-io.utils.js';
+import { getCrewlyHomePath } from '../core/crewly-home.utils.js';
+/** Current version of the state file schema */
+const STATE_VERSION = 1;
+/**
+ * Default state file location.
+ *
+ * Resolved via {@link getCrewlyHomePath} so test profiles (CREWLY_HOME=/tmp/...)
+ * read and write their own session-state.json instead of the user's real
+ * `~/.crewly/session-state.json`. Computed lazily inside the function so a
+ * test that sets `process.env.CREWLY_HOME` after module load still gets the
+ * override; the previous module-level constant captured `homedir()` at
+ * import time and silently leaked across profiles.
+ */
+function defaultStateFile() {
+    return path.join(getCrewlyHomePath(), 'session-state.json');
+}
+/**
+ * Session State Persistence Service
+ *
+ * Manages saving and restoring session state for PTY-based sessions.
+ * Sessions are saved when the backend shuts down and restored on startup.
+ *
+ * @example
+ * ```typescript
+ * const persistence = new SessionStatePersistence();
+ *
+ * // Register a session for persistence
+ * persistence.registerSession('my-session', options, 'claude-code', 'dev');
+ *
+ * // Save state on shutdown
+ * await persistence.saveState(backend);
+ *
+ * // Restore state on startup
+ * await persistence.restoreState(backend);
+ * ```
+ */
+export class SessionStatePersistence {
+    /** Path to the state file */
+    filePath;
+    /** Map of session name to metadata for persistence */
+    sessionMetadata = new Map();
+    /** Set of session names that were restored from the state file on startup */
+    restoredSessionNames = new Set();
+    /** Logger instance */
+    logger;
+    /**
+     * Create a new SessionStatePersistence instance.
+     *
+     * @param filePath - Optional custom path for the state file
+     */
+    constructor(filePath) {
+        this.filePath = filePath ?? defaultStateFile();
+        this.logger = LoggerService.getInstance().createComponentLogger('SessionPersistence');
+    }
+    /**
+     * Register a session for persistence tracking.
+     *
+     * @param name - Session name
+     * @param options - Session options used to create the session
+     * @param runtimeType - Type of runtime (claude-code, gemini-cli, codex-cli)
+     * @param role - Optional role for the agent
+     * @param teamId - Optional team ID
+     * @param memberId - Optional member ID for team member sessions
+     */
+    registerSession(name, options, runtimeType, role, teamId, memberId) {
+        this.sessionMetadata.set(name, {
+            name,
+            cwd: options.cwd,
+            command: options.command,
+            args: options.args ?? [],
+            runtimeType,
+            role,
+            teamId,
+            memberId,
+            env: options.env,
+        });
+        this.logger.debug('Registered session for persistence', { name, runtimeType, role });
+        this.autoSave().catch((err) => {
+            this.logger.warn('Auto-save after register failed', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+    }
+    /**
+     * Remove a session from persistence tracking.
+     *
+     * @param name - Session name to unregister
+     */
+    unregisterSession(name) {
+        const deleted = this.sessionMetadata.delete(name);
+        if (deleted) {
+            this.logger.debug('Unregistered session from persistence', { name });
+            this.autoSave().catch((err) => {
+                this.logger.warn('Auto-save after unregister failed', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
+    }
+    /**
+     * Check if a session is registered for persistence.
+     *
+     * @param name - Session name to check
+     * @returns true if the session is registered
+     */
+    isSessionRegistered(name) {
+        return this.sessionMetadata.has(name);
+    }
+    /**
+     * Get metadata for a registered session.
+     *
+     * @param name - Session name
+     * @returns Session metadata or undefined if not registered
+     */
+    getSessionMetadata(name) {
+        return this.sessionMetadata.get(name);
+    }
+    /**
+     * Update the Claude session ID for a registered session.
+     * Called when an agent registers via MCP and reports its session ID.
+     *
+     * @param name - Session name
+     * @param claudeSessionId - The Claude conversation/session ID
+     */
+    updateSessionId(name, claudeSessionId) {
+        const metadata = this.sessionMetadata.get(name);
+        if (metadata) {
+            metadata.claudeSessionId = claudeSessionId;
+            this.logger.info('Updated Claude session ID for persistence', { name, claudeSessionId });
+            this.autoSave().catch((err) => {
+                this.logger.warn('Auto-save after session ID update failed', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
+        else {
+            this.logger.warn('Cannot update session ID - session not registered', { name });
+        }
+    }
+    /**
+     * Get the Claude session ID for a registered session.
+     *
+     * @param name - Session name
+     * @returns Claude session ID or undefined
+     */
+    getSessionId(name) {
+        return this.sessionMetadata.get(name)?.claudeSessionId;
+    }
+    /**
+     * Check if a session was restored from the state file on startup.
+     *
+     * Sessions loaded during restoreState() are tracked separately from
+     * newly created sessions. This allows the resume logic to determine
+     * whether an agent was running before the backend restart.
+     *
+     * @param name - Session name to check
+     * @returns true if the session was restored from persisted state
+     */
+    isRestoredSession(name) {
+        return this.restoredSessionNames.has(name);
+    }
+    /**
+     * Get all registered session names.
+     *
+     * @returns Array of registered session names
+     */
+    getRegisteredSessions() {
+        return Array.from(this.sessionMetadata.keys());
+    }
+    /**
+     * Get all registered session metadata as a Map.
+     *
+     * @returns Map of session name to metadata
+     */
+    getRegisteredSessionsMap() {
+        return new Map(this.sessionMetadata);
+    }
+    /**
+     * Build the current persisted state object from in-memory metadata.
+     *
+     * @returns PersistedState snapshot
+     */
+    buildState() {
+        return {
+            version: STATE_VERSION,
+            savedAt: new Date().toISOString(),
+            sessions: Array.from(this.sessionMetadata.values()),
+        };
+    }
+    /**
+     * Auto-save current session metadata to disk.
+     * Called after register/unregister/updateSessionId to keep the state file
+     * in sync with in-memory metadata at all times. This ensures the state file
+     * is always up-to-date even if the process is killed before graceful shutdown.
+     */
+    async autoSave() {
+        try {
+            await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+            await atomicWriteJson(this.filePath, this.buildState());
+        }
+        catch (error) {
+            this.logger.warn('Failed to auto-save session state', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Save current session state to disk.
+     *
+     * Saves all sessions registered in sessionMetadata, which is the source
+     * of truth for what should persist.
+     *
+     * @param backend - Session backend (kept for backward compatibility, no longer used)
+     * @returns Number of sessions saved
+     */
+    async saveState(backend) {
+        try {
+            await this.autoSave();
+            const count = this.sessionMetadata.size;
+            this.logger.info('Saved session state', {
+                count,
+                sessions: Array.from(this.sessionMetadata.keys()),
+            });
+            return count;
+        }
+        catch (error) {
+            this.logger.error('Failed to save session state', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return 0;
+        }
+    }
+    /**
+     * Restore sessions from saved state.
+     *
+     * For Claude sessions, uses --resume flag to restore conversation context.
+     *
+     * @param backend - Session backend to create sessions in
+     * @returns Number of sessions successfully restored
+     */
+    async restoreState(backend) {
+        try {
+            const state = await safeReadJson(this.filePath, null, this.logger);
+            if (!state) {
+                this.logger.info('No saved session state found');
+                return 0;
+            }
+            if (state.version !== STATE_VERSION) {
+                this.logger.warn('Unknown state version, skipping restore', {
+                    version: state.version,
+                    expected: STATE_VERSION,
+                });
+                return 0;
+            }
+            let restored = 0;
+            const failed = [];
+            for (const sessionInfo of state.sessions) {
+                try {
+                    // For Claude, always use --resume to restore conversation
+                    const args = this.getRestoreArgs(sessionInfo);
+                    await backend.createSession(sessionInfo.name, {
+                        cwd: sessionInfo.cwd,
+                        command: sessionInfo.command,
+                        args,
+                        env: sessionInfo.env,
+                    });
+                    // Re-register metadata for future saves
+                    this.sessionMetadata.set(sessionInfo.name, sessionInfo);
+                    this.restoredSessionNames.add(sessionInfo.name);
+                    restored++;
+                    this.logger.info('Restored session', {
+                        name: sessionInfo.name,
+                        runtimeType: sessionInfo.runtimeType,
+                        hasClaudeSessionId: !!sessionInfo.claudeSessionId,
+                    });
+                }
+                catch (error) {
+                    failed.push(sessionInfo.name);
+                    this.logger.error('Failed to restore session', {
+                        name: sessionInfo.name,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            this.logger.info('Session restore complete', {
+                restored,
+                total: state.sessions.length,
+                failed: failed.length > 0 ? failed : undefined,
+            });
+            return restored;
+        }
+        catch (error) {
+            this.logger.error('Failed to restore session state', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return 0;
+        }
+    }
+    /**
+     * Get the arguments to use when restoring a session.
+     *
+     * The persisted command is the shell (e.g. /bin/zsh), not the Claude binary.
+     * Claude Code is launched inside the shell by initializeAgentWithRegistration,
+     * so we must NOT add --resume to the shell args — it would cause
+     * "/bin/zsh: no such option: resume".
+     *
+     * @param sessionInfo - Session metadata
+     * @returns Arguments array for session creation
+     */
+    getRestoreArgs(sessionInfo) {
+        // Return original args as-is. The persisted command is the shell,
+        // not the runtime binary — flags like --resume belong on the runtime
+        // command which is launched separately during initialization.
+        return [...sessionInfo.args];
+    }
+    /**
+     * Clear the saved state file.
+     */
+    async clearState() {
+        try {
+            await fs.unlink(this.filePath);
+            this.logger.info('Cleared session state file');
+        }
+        catch (error) {
+            const errno = error;
+            if (errno.code !== 'ENOENT') {
+                this.logger.error('Failed to clear session state file', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    /**
+     * Clear both in-memory metadata and the state file on disk.
+     * Used when the user dismisses the session resume popup.
+     */
+    async clearStateAndMetadata() {
+        this.sessionMetadata.clear();
+        this.restoredSessionNames.clear();
+        await this.clearState();
+        this.logger.info('Cleared session metadata and state file');
+    }
+    /**
+     * Clear all registered session metadata (in-memory only).
+     */
+    clearMetadata() {
+        this.sessionMetadata.clear();
+        this.restoredSessionNames.clear();
+        this.logger.debug('Cleared session metadata');
+    }
+    /**
+     * Get the path to the state file.
+     *
+     * @returns State file path
+     */
+    getFilePath() {
+        return this.filePath;
+    }
+    /**
+     * Load state from file without restoring sessions.
+     *
+     * @returns Persisted state or null if not found/invalid
+     */
+    async loadState() {
+        const state = await safeReadJson(this.filePath, null, this.logger);
+        if (!state) {
+            return null;
+        }
+        if (state.version !== STATE_VERSION) {
+            this.logger.warn('Unknown state version', { version: state.version });
+            return null;
+        }
+        return state;
+    }
+}
+/** Singleton instance for application-wide use */
+let _instance = null;
+/**
+ * Get the singleton SessionStatePersistence instance.
+ *
+ * @returns SessionStatePersistence instance
+ */
+export function getSessionStatePersistence() {
+    if (!_instance) {
+        _instance = new SessionStatePersistence();
+    }
+    return _instance;
+}
+/**
+ * Reset the singleton instance (for testing).
+ */
+export function resetSessionStatePersistence() {
+    _instance = null;
+}
+//# sourceMappingURL=session-state-persistence.js.map

package/dist/cli/backend/src/services/session/session-state-persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-state-persistence.js","sourceRoot":"","sources":["../../../../../../backend/src/services/session/session-state-persistence.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/services/settings/role.service.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Role Management Service
+ *
+ * Handles CRUD operations for AI agent roles, loading from configuration
+ * directories, and managing role-to-skill assignments.
+ *
+ * @module services/settings/role.service
+ */
+import { Role, RoleWithPrompt, RoleSummary, CreateRoleInput, UpdateRoleInput, RoleFilter } from '../../types/role.types.js';
+/**
+ * Error thrown when a role is not found
+ */
+export declare class RoleNotFoundError extends Error {
+    constructor(id: string);
+}
+/**
+ * Error thrown when role validation fails
+ */
+export declare class RoleValidationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * Error thrown when attempting to modify a built-in role
+ */
+export declare class BuiltinRoleModificationError extends Error {
+    constructor(action: string);
+}
+/**
+ * Error thrown when a role with the same name already exists
+ */
+export declare class DuplicateRoleNameError extends Error {
+    constructor(name: string);
+}
+/**
+ * Service for managing AI agent roles
+ *
+ * Handles:
+ * - Loading built-in roles from config/roles/
+ * - Managing user-created roles in ~/.crewly/roles/
+ * - CRUD operations for roles
+ * - Role-to-skill assignment management
+ *
+ * @example
+ * ```typescript
+ * const service = getRoleService();
+ * await service.initialize();
+ *
+ * // List all roles
+ * const roles = await service.listRoles();
+ *
+ * // Create a new role
+ * const newRole = await service.createRole({
+ *   name: 'my-role',
+ *   displayName: 'My Role',
+ *   description: 'A custom role',
+ *   category: 'development',
+ *   systemPromptContent: 'You are a helpful assistant.',
+ * });
+ * ```
+ */
+export declare class RoleService {
+    private readonly builtinRolesDir;
+    private readonly userRolesDir;
+    private rolesCache;
+    private promptCache;
+    private initialized;
+    private readonly logger;
+    /**
+     * Create a new RoleService instance
+     *
+     * @param options - Configuration options
+     * @param options.builtinRolesDir - Directory for built-in roles
+     * @param options.userRolesDir - Directory for user-created roles
+     */
+    constructor(options?: {
+        builtinRolesDir?: string;
+        userRolesDir?: string;
+    });
+    /**
+     * Initialize the service by loading all roles
+     * Must be called before using other methods
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get all roles, optionally filtered
+     *
+     * @param filter - Optional filter criteria
+     * @param includeHidden - Whether to include hidden roles (default: false for UI)
+     * @returns Array of role summaries
+     */
+    listRoles(filter?: RoleFilter, includeHidden?: boolean): Promise<RoleSummary[]>;
+    /**
+     * Get a role by ID with full prompt content
+     *
+     * @param id - The role ID
+     * @returns The role with prompt content, or null if not found
+     */
+    getRole(id: string): Promise<RoleWithPrompt | null>;
+    /**
+     * Get a role by name (includes hidden roles)
+     *
+     * @param name - The role name
+     * @returns The role with prompt content, or null if not found
+     */
+    getRoleByName(name: string): Promise<RoleWithPrompt | null>;
+    /**
+     * Get the prompt file path for a role
+     * Used by PromptBuilderService and AgentRegistrationService
+     *
+     * @param roleName - The role name (e.g., 'orchestrator', 'tpm', 'developer')
+     * @returns The full path to the prompt file, or null if role not found
+     */
+    getPromptFilePath(roleName: string): Promise<string | null>;
+    /**
+     * Get the built-in roles directory path
+     *
+     * @returns The path to built-in roles directory
+     */
+    getBuiltinRolesDir(): string;
+    /**
+     * Create a new user-defined role
+     *
+     * @param input - The role creation input
+     * @returns The created role
+     * @throws {RoleValidationError} If input validation fails
+     * @throws {DuplicateRoleNameError} If a role with the same name exists
+     */
+    createRole(input: CreateRoleInput): Promise<Role>;
+    /**
+     * Update an existing role
+     *
+     * For builtin roles: Creates an override in ~/.crewly/roles/ (original stays intact)
+     * For user roles: Updates the role directly
+     *
+     * @param id - The role ID
+     * @param input - The update input
+     * @returns The updated role
+     * @throws {RoleNotFoundError} If the role is not found
+     * @throws {RoleValidationError} If input validation fails
+     */
+    updateRole(id: string, input: UpdateRoleInput): Promise<Role>;
+    /**
+     * Check if a builtin role has a user override
+     *
+     * @param id - The role ID
+     * @returns True if the role has a user override
+     */
+    hasOverride(id: string): Promise<boolean>;
+    /**
+     * Reset a builtin role to its default (removes user override)
+     *
+     * @param id - The role ID
+     * @returns The reset role (original builtin values)
+     * @throws {RoleNotFoundError} If the role is not found
+     */
+    resetToDefault(id: string): Promise<Role>;
+    /**
+     * Delete a user-created role (built-in roles cannot be deleted)
+     *
+     * @param id - The role ID
+     * @throws {RoleNotFoundError} If the role is not found
+     * @throws {BuiltinRoleModificationError} If attempting to delete a built-in role
+     */
+    deleteRole(id: string): Promise<void>;
+    /**
+     * Assign skills to a role
+     *
+     * @param roleId - The role ID
+     * @param skillIds - Array of skill IDs to assign
+     * @returns The updated role
+     * @throws {RoleNotFoundError} If the role is not found
+     * @throws {BuiltinRoleModificationError} If attempting to modify a built-in role
+     */
+    assignSkills(roleId: string, skillIds: string[]): Promise<Role>;
+    /**
+     * Remove skills from a role
+     *
+     * @param roleId - The role ID
+     * @param skillIds - Array of skill IDs to remove
+     * @returns The updated role
+     * @throws {RoleNotFoundError} If the role is not found
+     * @throws {BuiltinRoleModificationError} If attempting to modify a built-in role
+     */
+    removeSkills(roleId: string, skillIds: string[]): Promise<Role>;
+    /**
+     * Set the default role
+     *
+     * @param roleId - The role ID to set as default
+     * @returns The updated role
+     * @throws {RoleNotFoundError} If the role is not found
+     */
+    setDefaultRole(roleId: string): Promise<Role>;
+    /**
+     * Get the current default role
+     *
+     * @returns The default role, or null if none is set
+     */
+    getDefaultRole(): Promise<Role | null>;
+    /**
+     * Refresh the roles cache by reloading from disk
+     */
+    refresh(): Promise<void>;
+    /**
+     * Ensure the service is initialized.
+     * Auto-initializes if not already done.
+     */
+    private ensureInitialized;
+    /**
+     * Load built-in roles from the config directory
+     * Loads from subdirectories (config/roles/{role}/role.json)
+     */
+    private loadBuiltinRoles;
+    /**
+     * Load user-created roles from the user directory
+     */
+    private loadUserRoles;
+    /**
+     * Save a role and its prompt content to disk
+     *
+     * @param role - The role to save
+     * @param promptContent - The prompt content to save
+     */
+    private saveRole;
+    /**
+     * Save a role override to user directory
+     * Uses subdirectory structure: ~/.crewly/roles/{role-name}/role.json + prompt.md
+     *
+     * @param role - The role to save
+     * @param promptContent - The prompt content
+     */
+    private saveRoleOverride;
+    /**
+     * Load prompt content from a file
+     * For built-in roles, checks for user override first, then falls back to builtin
+     * For user roles, loads from ~/.crewly/roles/
+     *
+     * @param promptFile - The prompt file name (e.g., "prompt.md")
+     * @param isBuiltin - Whether this is a built-in role
+     * @param roleName - The role name (directory name)
+     * @returns The prompt content
+     */
+    private loadPromptContent;
+    /**
+     * Ensure the user roles directory exists
+     */
+    private ensureUserRolesDir;
+    /**
+     * Generate a unique role ID
+     *
+     * @param name - The role name
+     * @returns A unique ID
+     */
+    private generateRoleId;
+    /**
+     * Sanitize a role name for use in file names
+     *
+     * @param name - The role name
+     * @returns The sanitized name
+     */
+    private sanitizeRoleName;
+    /**
+     * Unset isDefault on all roles
+     */
+    private unsetAllDefaults;
+}
+/**
+ * Get the singleton RoleService instance
+ *
+ * @returns The RoleService instance
+ */
+export declare function getRoleService(): RoleService;
+/**
+ * Reset the singleton instance (for testing)
+ */
+export declare function resetRoleService(): void;
+//# sourceMappingURL=role.service.d.ts.map