mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-03 15:43:11 +08:00
Add comprehensive tests for keyword detection, session state management, and user abort detection
- Implement tests for KeywordDetector including keyword detection, sanitization, and priority handling. - Add tests for SessionStateService covering session validation, loading, saving, and state updates. - Create tests for UserAbortDetector to validate user abort detection logic and pattern matching.
This commit is contained in:
catlog22
120
ccw/src/core/hooks/context-limit-detector.ts
Normal file
120
ccw/src/core/hooks/context-limit-detector.ts
Normal file
@@ -0,0 +1,120 @@
|
||||
/**
|
||||
* ContextLimitDetector - Detects context limit stops
|
||||
*
|
||||
* When context is exhausted, Claude Code needs to stop so it can compact.
|
||||
* Blocking these stops causes a deadlock: can't compact because can't stop,
|
||||
* can't continue because context is full.
|
||||
*
|
||||
* This detector identifies context-limit related stop reasons to allow
|
||||
* graceful handling of context exhaustion.
|
||||
*
|
||||
* @see https://github.com/Yeachan-Heo/oh-my-claudecode/issues/213
|
||||
*/
|
||||
|
||||
/**
|
||||
* Context from Stop hook event
|
||||
*
|
||||
* NOTE: Field names support both camelCase and snake_case variants
|
||||
* for compatibility with different Claude Code versions.
|
||||
*/
|
||||
export interface StopContext {
|
||||
/** Reason for stop (from Claude Code) - snake_case variant */
|
||||
stop_reason?: string;
|
||||
/** Reason for stop (from Claude Code) - camelCase variant */
|
||||
stopReason?: string;
|
||||
/** End turn reason (from API) - snake_case variant */
|
||||
end_turn_reason?: string;
|
||||
/** End turn reason (from API) - camelCase variant */
|
||||
endTurnReason?: string;
|
||||
/** Whether user explicitly requested stop - snake_case variant */
|
||||
user_requested?: boolean;
|
||||
/** Whether user explicitly requested stop - camelCase variant */
|
||||
userRequested?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Patterns that indicate context limit has been reached
|
||||
*
|
||||
* These patterns are matched case-insensitively against stop_reason
|
||||
* and end_turn_reason fields.
|
||||
*/
|
||||
export const CONTEXT_LIMIT_PATTERNS: readonly string[] = [
|
||||
'context_limit',
|
||||
'context_window',
|
||||
'context_exceeded',
|
||||
'context_full',
|
||||
'max_context',
|
||||
'token_limit',
|
||||
'max_tokens',
|
||||
'conversation_too_long',
|
||||
'input_too_long'
|
||||
] as const;
|
||||
|
||||
/**
|
||||
* Check if a reason string matches any context limit pattern
|
||||
*
|
||||
* @param reason - The reason string to check
|
||||
* @returns true if the reason matches a context limit pattern
|
||||
*/
|
||||
function matchesContextPattern(reason: string): boolean {
|
||||
const normalizedReason = reason.toLowerCase();
|
||||
return CONTEXT_LIMIT_PATTERNS.some(pattern => normalizedReason.includes(pattern));
|
||||
}
|
||||
|
||||
/**
|
||||
* Detect if stop was triggered by context-limit related reasons
|
||||
*
|
||||
* When context is exhausted, Claude Code needs to stop so it can compact.
|
||||
* Blocking these stops causes a deadlock: can't compact because can't stop,
|
||||
* can't continue because context is full.
|
||||
*
|
||||
* @param context - The stop context from the hook event
|
||||
* @returns true if the stop was due to context limit
|
||||
*/
|
||||
export function isContextLimitStop(context?: StopContext): boolean {
|
||||
if (!context) return false;
|
||||
|
||||
// Get reasons from both field naming conventions
|
||||
const stopReason = context.stop_reason ?? context.stopReason ?? '';
|
||||
const endTurnReason = context.end_turn_reason ?? context.endTurnReason ?? '';
|
||||
|
||||
// Check both stop_reason and end_turn_reason for context limit patterns
|
||||
return matchesContextPattern(stopReason) || matchesContextPattern(endTurnReason);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the matching context limit pattern if any
|
||||
*
|
||||
* @param context - The stop context from the hook event
|
||||
* @returns The matching pattern or null if no match
|
||||
*/
|
||||
export function getMatchingContextPattern(context?: StopContext): string | null {
|
||||
if (!context) return null;
|
||||
|
||||
const stopReason = (context.stop_reason ?? context.stopReason ?? '').toLowerCase();
|
||||
const endTurnReason = (context.end_turn_reason ?? context.endTurnReason ?? '').toLowerCase();
|
||||
|
||||
for (const pattern of CONTEXT_LIMIT_PATTERNS) {
|
||||
if (stopReason.includes(pattern) || endTurnReason.includes(pattern)) {
|
||||
return pattern;
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all matching context limit patterns
|
||||
*
|
||||
* @param context - The stop context from the hook event
|
||||
* @returns Array of matching patterns (may be empty)
|
||||
*/
|
||||
export function getAllMatchingContextPatterns(context?: StopContext): string[] {
|
||||
if (!context) return [];
|
||||
|
||||
const stopReason = (context.stop_reason ?? context.stopReason ?? '').toLowerCase();
|
||||
const endTurnReason = (context.end_turn_reason ?? context.endTurnReason ?? '').toLowerCase();
|
||||
const combinedReasons = `${stopReason} ${endTurnReason}`;
|
||||
|
||||
return CONTEXT_LIMIT_PATTERNS.filter(pattern => combinedReasons.includes(pattern));
|
||||
}
|
||||
60
ccw/src/core/hooks/index.ts
Normal file
60
ccw/src/core/hooks/index.ts
Normal file
@@ -0,0 +1,60 @@
|
||||
/**
|
||||
* Core Hooks Module
|
||||
*
|
||||
* Provides detector functions and utilities for Claude Code hooks integration.
|
||||
*/
|
||||
|
||||
// Context Limit Detector
|
||||
export {
|
||||
isContextLimitStop,
|
||||
getMatchingContextPattern,
|
||||
getAllMatchingContextPatterns,
|
||||
CONTEXT_LIMIT_PATTERNS,
|
||||
type StopContext
|
||||
} from './context-limit-detector.js';
|
||||
|
||||
// User Abort Detector
|
||||
export {
|
||||
isUserAbort,
|
||||
getMatchingAbortPattern,
|
||||
getAllMatchingAbortPatterns,
|
||||
shouldAllowContinuation,
|
||||
USER_ABORT_EXACT_PATTERNS,
|
||||
USER_ABORT_SUBSTRING_PATTERNS,
|
||||
USER_ABORT_PATTERNS
|
||||
} from './user-abort-detector.js';
|
||||
|
||||
// Keyword Detector
|
||||
export {
|
||||
detectKeywords,
|
||||
hasKeyword,
|
||||
getAllKeywords,
|
||||
getPrimaryKeyword,
|
||||
getKeywordType,
|
||||
hasKeywordType,
|
||||
sanitizeText,
|
||||
removeCodeBlocks,
|
||||
KEYWORD_PATTERNS,
|
||||
KEYWORD_PRIORITY,
|
||||
type KeywordType,
|
||||
type DetectedKeyword
|
||||
} from './keyword-detector.js';
|
||||
|
||||
// Stop Handler
|
||||
export {
|
||||
StopHandler,
|
||||
createStopHandler,
|
||||
defaultStopHandler,
|
||||
type ExtendedStopContext,
|
||||
type StopResult,
|
||||
type StopHandlerOptions
|
||||
} from './stop-handler.js';
|
||||
|
||||
// Recovery Handler
|
||||
export {
|
||||
RecoveryHandler,
|
||||
createRecoveryHandler,
|
||||
type PreCompactInput,
|
||||
type HookOutput,
|
||||
type RecoveryHandlerOptions
|
||||
} from './recovery-handler.js';
|
||||
261
ccw/src/core/hooks/keyword-detector.ts
Normal file
261
ccw/src/core/hooks/keyword-detector.ts
Normal file
@@ -0,0 +1,261 @@
|
||||
/**
|
||||
* KeywordDetector - Detects magic keywords in user prompts
|
||||
*
|
||||
* Detects magic keywords in user prompts and returns the appropriate
|
||||
* mode message to inject into context.
|
||||
*
|
||||
* Ported from oh-my-opencode's keyword-detector hook with adaptations
|
||||
* for CCW architecture.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Supported keyword types for mode detection
|
||||
*/
|
||||
export type KeywordType =
|
||||
| 'cancel' // Priority 1: Cancel all operations
|
||||
| 'ralph' // Priority 2: Ralph mode
|
||||
| 'autopilot' // Priority 3: Auto-pilot mode
|
||||
| 'ultrapilot' // Priority 4: Ultra-pilot mode (parallel build)
|
||||
| 'team' // Priority 4.5: Team mode (coordinated agents)
|
||||
| 'ultrawork' // Priority 5: Ultra-work mode
|
||||
| 'swarm' // Priority 6: Swarm mode (multiple agents)
|
||||
| 'pipeline' // Priority 7: Pipeline mode (chained agents)
|
||||
| 'ralplan' // Priority 8: Ralplan mode
|
||||
| 'plan' // Priority 9: Planning mode
|
||||
| 'tdd' // Priority 10: Test-driven development mode
|
||||
| 'ultrathink' // Priority 11: Deep thinking mode
|
||||
| 'deepsearch' // Priority 12: Deep search mode
|
||||
| 'analyze' // Priority 13: Analysis mode
|
||||
| 'codex' // Priority 14: Delegate to Codex
|
||||
| 'gemini'; // Priority 15: Delegate to Gemini
|
||||
|
||||
/**
|
||||
* Detected keyword with metadata
|
||||
*/
|
||||
export interface DetectedKeyword {
|
||||
/** Type of the detected keyword */
|
||||
type: KeywordType;
|
||||
/** The actual matched keyword string */
|
||||
keyword: string;
|
||||
/** Position in the original text where the keyword was found */
|
||||
position: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Keyword patterns for each mode
|
||||
*/
|
||||
export const KEYWORD_PATTERNS: Record<KeywordType, RegExp> = {
|
||||
cancel: /\b(cancelomc|stopomc)\b/i,
|
||||
ralph: /\b(ralph)\b/i,
|
||||
autopilot: /\b(autopilot|auto[\s-]?pilot|fullsend|full\s+auto)\b/i,
|
||||
ultrapilot: /\b(ultrapilot|ultra-pilot)\b|\bparallel\s+build\b|\bswarm\s+build\b/i,
|
||||
ultrawork: /\b(ultrawork|ulw)\b/i,
|
||||
swarm: /\bswarm\s+\d+\s+agents?\b|\bcoordinated\s+agents\b|\bteam\s+mode\b/i,
|
||||
team: /(?<!\b(?:my|the|our|a|his|her|their|its)\s)\bteam\b|\bcoordinated\s+team\b/i,
|
||||
pipeline: /\bagent\s+pipeline\b|\bchain\s+agents\b/i,
|
||||
ralplan: /\b(ralplan)\b/i,
|
||||
plan: /\bplan\s+(this|the)\b/i,
|
||||
tdd: /\b(tdd)\b|\btest\s+first\b/i,
|
||||
ultrathink: /\b(ultrathink)\b/i,
|
||||
deepsearch: /\b(deepsearch)\b|\bsearch\s+the\s+codebase\b|\bfind\s+in\s+(the\s+)?codebase\b/i,
|
||||
analyze: /\b(deep[\s-]?analyze|deepanalyze)\b/i,
|
||||
codex: /\b(ask|use|delegate\s+to)\s+(codex|gpt)\b/i,
|
||||
gemini: /\b(ask|use|delegate\s+to)\s+gemini\b/i
|
||||
};
|
||||
|
||||
/**
|
||||
* Priority order for keyword detection
|
||||
* Higher priority keywords are checked first and take precedence in conflict resolution
|
||||
*/
|
||||
export const KEYWORD_PRIORITY: KeywordType[] = [
|
||||
'cancel', 'ralph', 'autopilot', 'ultrapilot', 'team', 'ultrawork',
|
||||
'swarm', 'pipeline', 'ralplan', 'plan', 'tdd',
|
||||
'ultrathink', 'deepsearch', 'analyze', 'codex', 'gemini'
|
||||
];
|
||||
|
||||
/**
|
||||
* Remove code blocks from text to prevent false positives
|
||||
* Handles both fenced code blocks and inline code
|
||||
*
|
||||
* @param text - The text to clean
|
||||
* @returns Text with code blocks removed
|
||||
*/
|
||||
export function removeCodeBlocks(text: string): string {
|
||||
// Remove fenced code blocks (``` or ~~~)
|
||||
let result = text.replace(/```[\s\S]*?```/g, '');
|
||||
result = result.replace(/~~~[\s\S]*?~~~/g, '');
|
||||
|
||||
// Remove inline code (single backticks)
|
||||
result = result.replace(/`[^`]+`/g, '');
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sanitize text for keyword detection by removing structural noise.
|
||||
* Strips XML tags, URLs, file paths, and code blocks.
|
||||
*
|
||||
* @param text - The text to sanitize
|
||||
* @returns Sanitized text ready for keyword detection
|
||||
*/
|
||||
export function sanitizeText(text: string): string {
|
||||
// Remove XML tag blocks (opening + content + closing; tag names must match)
|
||||
let result = text.replace(/<(\w[\w-]*)[\s>][\s\S]*?<\/\1>/g, '');
|
||||
// Remove self-closing XML tags
|
||||
result = result.replace(/<\w[\w-]*(?:\s[^>]*)?\s*\/>/g, '');
|
||||
// Remove URLs
|
||||
result = result.replace(/https?:\/\/\S+/g, '');
|
||||
// Remove file paths - requires leading / or ./ or multi-segment dir/file.ext
|
||||
result = result.replace(/(^|[\s"'`(])(?:\.?\/(?:[\w.-]+\/)*[\w.-]+|(?:[\w.-]+\/)+[\w.-]+\.\w+)/gm, '$1');
|
||||
// Remove code blocks (fenced and inline)
|
||||
result = removeCodeBlocks(result);
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Detect keywords in text and return matches with type info
|
||||
*
|
||||
* @param text - The text to analyze
|
||||
* @param options - Optional configuration
|
||||
* @returns Array of detected keywords with metadata
|
||||
*/
|
||||
export function detectKeywords(
|
||||
text: string,
|
||||
options?: { teamEnabled?: boolean }
|
||||
): DetectedKeyword[] {
|
||||
const detected: DetectedKeyword[] = [];
|
||||
const cleanedText = sanitizeText(text);
|
||||
const teamEnabled = options?.teamEnabled ?? false;
|
||||
|
||||
// Check each keyword type in priority order
|
||||
for (const type of KEYWORD_PRIORITY) {
|
||||
// Skip team-related types when team feature is disabled
|
||||
if ((type === 'team' || type === 'ultrapilot' || type === 'swarm') && !teamEnabled) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const pattern = KEYWORD_PATTERNS[type];
|
||||
const match = cleanedText.match(pattern);
|
||||
|
||||
if (match && match.index !== undefined) {
|
||||
detected.push({
|
||||
type,
|
||||
keyword: match[0],
|
||||
position: match.index
|
||||
});
|
||||
|
||||
// Legacy ultrapilot/swarm also activate team mode internally
|
||||
if (teamEnabled && (type === 'ultrapilot' || type === 'swarm')) {
|
||||
detected.push({
|
||||
type: 'team',
|
||||
keyword: match[0],
|
||||
position: match.index
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return detected;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if text contains any magic keyword
|
||||
*
|
||||
* @param text - The text to check
|
||||
* @returns true if any keyword is detected
|
||||
*/
|
||||
export function hasKeyword(text: string): boolean {
|
||||
return detectKeywords(text).length > 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all detected keywords with conflict resolution applied
|
||||
*
|
||||
* Conflict resolution rules:
|
||||
* - cancel suppresses everything (exclusive)
|
||||
* - team beats autopilot (mutual exclusion)
|
||||
*
|
||||
* @param text - The text to analyze
|
||||
* @param options - Optional configuration
|
||||
* @returns Array of resolved keyword types in priority order
|
||||
*/
|
||||
export function getAllKeywords(
|
||||
text: string,
|
||||
options?: { teamEnabled?: boolean }
|
||||
): KeywordType[] {
|
||||
const detected = detectKeywords(text, options);
|
||||
|
||||
if (detected.length === 0) return [];
|
||||
|
||||
let types = Array.from(new Set(detected.map(d => d.type)));
|
||||
|
||||
// Exclusive: cancel suppresses everything
|
||||
if (types.includes('cancel')) return ['cancel'];
|
||||
|
||||
// Mutual exclusion: team beats autopilot (ultrapilot/swarm now map to team at detection)
|
||||
if (types.includes('team') && types.includes('autopilot')) {
|
||||
types = types.filter(t => t !== 'autopilot');
|
||||
}
|
||||
|
||||
// Sort by priority order
|
||||
return KEYWORD_PRIORITY.filter(k => types.includes(k));
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the highest priority keyword detected with conflict resolution
|
||||
*
|
||||
* @param text - The text to analyze
|
||||
* @param options - Optional configuration
|
||||
* @returns The primary detected keyword or null if none found
|
||||
*/
|
||||
export function getPrimaryKeyword(
|
||||
text: string,
|
||||
options?: { teamEnabled?: boolean }
|
||||
): DetectedKeyword | null {
|
||||
const allKeywords = getAllKeywords(text, options);
|
||||
|
||||
if (allKeywords.length === 0) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Get the highest priority keyword type
|
||||
const primaryType = allKeywords[0];
|
||||
|
||||
// Find the original detected keyword for this type
|
||||
const detected = detectKeywords(text, options);
|
||||
const match = detected.find(d => d.type === primaryType);
|
||||
|
||||
return match || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get keyword type for a given keyword string
|
||||
*
|
||||
* @param keyword - The keyword string to look up
|
||||
* @returns The keyword type or null if not found
|
||||
*/
|
||||
export function getKeywordType(keyword: string): KeywordType | null {
|
||||
const normalizedKeyword = keyword.toLowerCase();
|
||||
|
||||
for (const type of KEYWORD_PRIORITY) {
|
||||
const pattern = KEYWORD_PATTERNS[type];
|
||||
if (pattern.test(normalizedKeyword)) {
|
||||
return type;
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a specific keyword type is detected in text
|
||||
*
|
||||
* @param text - The text to check
|
||||
* @param type - The keyword type to look for
|
||||
* @returns true if the keyword type is detected
|
||||
*/
|
||||
export function hasKeywordType(text: string, type: KeywordType): boolean {
|
||||
const cleanedText = sanitizeText(text);
|
||||
const pattern = KEYWORD_PATTERNS[type];
|
||||
return pattern.test(cleanedText);
|
||||
}
|
||||
328
ccw/src/core/hooks/recovery-handler.ts
Normal file
328
ccw/src/core/hooks/recovery-handler.ts
Normal file
@@ -0,0 +1,328 @@
|
||||
/**
|
||||
* RecoveryHandler - Session Recovery and PreCompact Handler
|
||||
*
|
||||
* Handles PreCompact hook events and session recovery for state preservation
|
||||
* during context compaction and session restarts.
|
||||
*
|
||||
* Features:
|
||||
* - PreCompact checkpoint creation before context compaction
|
||||
* - Session recovery detection and message injection
|
||||
* - Mutex lock to prevent concurrent compaction operations
|
||||
*
|
||||
* Based on oh-my-claudecode pre-compact pattern.
|
||||
*/
|
||||
|
||||
import type { Checkpoint, CheckpointTrigger } from '../services/checkpoint-service.js';
|
||||
|
||||
// =============================================================================
|
||||
// Types
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Input from PreCompact hook event
|
||||
*/
|
||||
export interface PreCompactInput {
|
||||
/** Session ID */
|
||||
session_id: string;
|
||||
/** Path to transcript file */
|
||||
transcript_path?: string;
|
||||
/** Current working directory */
|
||||
cwd: string;
|
||||
/** Permission mode */
|
||||
permission_mode?: string;
|
||||
/** Hook event name */
|
||||
hook_event_name: 'PreCompact';
|
||||
/** Trigger type */
|
||||
trigger: 'manual' | 'auto';
|
||||
/** Custom instructions */
|
||||
custom_instructions?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Output for hook handlers
|
||||
*/
|
||||
export interface HookOutput {
|
||||
/** Whether to continue with the operation */
|
||||
continue: boolean;
|
||||
/** System message for context injection */
|
||||
systemMessage?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Options for RecoveryHandler
|
||||
*/
|
||||
export interface RecoveryHandlerOptions {
|
||||
/** Project root path */
|
||||
projectPath: string;
|
||||
/** Enable logging */
|
||||
enableLogging?: boolean;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Compaction Mutex
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Per-directory in-flight compaction promises.
|
||||
* When a compaction is already running for a directory, new callers
|
||||
* await the existing promise instead of running concurrently.
|
||||
* This prevents race conditions when multiple subagent results
|
||||
* arrive simultaneously (swarm/ultrawork).
|
||||
*/
|
||||
const inflightCompactions = new Map<string, Promise<HookOutput>>();
|
||||
|
||||
/**
|
||||
* Queue depth counter per directory for diagnostics.
|
||||
* Tracks how many callers are waiting on an in-flight compaction.
|
||||
*/
|
||||
const compactionQueueDepth = new Map<string, number>();
|
||||
|
||||
// =============================================================================
|
||||
// RecoveryHandler Class
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Handler for PreCompact hook events and session recovery
|
||||
*/
|
||||
export class RecoveryHandler {
|
||||
private projectPath: string;
|
||||
private enableLogging: boolean;
|
||||
|
||||
constructor(options: RecoveryHandlerOptions) {
|
||||
this.projectPath = options.projectPath;
|
||||
this.enableLogging = options.enableLogging ?? false;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: PreCompact Handler
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Handle PreCompact hook event
|
||||
*
|
||||
* Creates a checkpoint before compaction to preserve state.
|
||||
* Uses mutex to prevent concurrent compaction for the same directory.
|
||||
*
|
||||
* @param input - PreCompact hook input
|
||||
* @returns Promise resolving to hook output with checkpoint summary
|
||||
*/
|
||||
async handlePreCompact(input: PreCompactInput): Promise<HookOutput> {
|
||||
const directory = input.cwd || this.projectPath;
|
||||
|
||||
// Check for in-flight compaction
|
||||
const inflight = inflightCompactions.get(directory);
|
||||
if (inflight) {
|
||||
const depth = (compactionQueueDepth.get(directory) ?? 0) + 1;
|
||||
compactionQueueDepth.set(directory, depth);
|
||||
try {
|
||||
// Await the existing compaction result
|
||||
return await inflight;
|
||||
} finally {
|
||||
const current = compactionQueueDepth.get(directory) ?? 1;
|
||||
if (current <= 1) {
|
||||
compactionQueueDepth.delete(directory);
|
||||
} else {
|
||||
compactionQueueDepth.set(directory, current - 1);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// No in-flight compaction - run it and register the promise
|
||||
const compactionPromise = this.doHandlePreCompact(input);
|
||||
inflightCompactions.set(directory, compactionPromise);
|
||||
|
||||
try {
|
||||
return await compactionPromise;
|
||||
} finally {
|
||||
inflightCompactions.delete(directory);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Internal PreCompact handler (unserialized)
|
||||
*/
|
||||
private async doHandlePreCompact(input: PreCompactInput): Promise<HookOutput> {
|
||||
this.log(`Creating checkpoint for session ${input.session_id} (trigger: ${input.trigger})`);
|
||||
|
||||
try {
|
||||
// Import services dynamically
|
||||
const { CheckpointService } = await import('../services/checkpoint-service.js');
|
||||
const { ModeRegistryService } = await import('../services/mode-registry-service.js');
|
||||
|
||||
// Create checkpoint service
|
||||
const checkpointService = new CheckpointService({
|
||||
projectPath: this.projectPath,
|
||||
enableLogging: this.enableLogging
|
||||
});
|
||||
|
||||
// Get mode registry for active modes
|
||||
const modeRegistry = new ModeRegistryService({
|
||||
projectPath: this.projectPath,
|
||||
enableLogging: this.enableLogging
|
||||
});
|
||||
|
||||
// Collect active mode states
|
||||
const activeModes = modeRegistry.getActiveModes(input.session_id);
|
||||
const modeStates: Record<string, { active: boolean; phase?: string; activatedAt?: string }> = {};
|
||||
|
||||
for (const mode of activeModes) {
|
||||
modeStates[mode] = {
|
||||
active: true,
|
||||
activatedAt: new Date().toISOString()
|
||||
};
|
||||
}
|
||||
|
||||
// Create checkpoint
|
||||
const trigger: CheckpointTrigger = input.trigger === 'manual' ? 'manual' : 'compact';
|
||||
const checkpoint = await checkpointService.createCheckpoint(
|
||||
input.session_id,
|
||||
trigger,
|
||||
{
|
||||
modeStates: modeStates as any,
|
||||
workflowState: null,
|
||||
memoryContext: null
|
||||
}
|
||||
);
|
||||
|
||||
// Save checkpoint
|
||||
await checkpointService.saveCheckpoint(checkpoint);
|
||||
|
||||
// Format recovery message
|
||||
const systemMessage = checkpointService.formatRecoveryMessage(checkpoint);
|
||||
|
||||
this.log(`Checkpoint created: ${checkpoint.id}`);
|
||||
|
||||
return {
|
||||
continue: true,
|
||||
systemMessage
|
||||
};
|
||||
} catch (error) {
|
||||
this.log(`Error creating checkpoint: ${(error as Error).message}`);
|
||||
|
||||
// Return success even on error - don't block compaction
|
||||
return {
|
||||
continue: true,
|
||||
systemMessage: `[PRECOMPACT WARNING] Checkpoint creation failed: ${(error as Error).message}. Proceeding with compaction.`
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Recovery Detection
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Check for recoverable checkpoint for a session
|
||||
*
|
||||
* @param sessionId - The session ID to check
|
||||
* @returns The most recent checkpoint or null if none found
|
||||
*/
|
||||
async checkRecovery(sessionId: string): Promise<Checkpoint | null> {
|
||||
try {
|
||||
const { CheckpointService } = await import('../services/checkpoint-service.js');
|
||||
|
||||
const checkpointService = new CheckpointService({
|
||||
projectPath: this.projectPath,
|
||||
enableLogging: this.enableLogging
|
||||
});
|
||||
|
||||
const checkpoint = await checkpointService.getLatestCheckpoint(sessionId);
|
||||
|
||||
if (checkpoint) {
|
||||
this.log(`Found recoverable checkpoint: ${checkpoint.id} (trigger: ${checkpoint.trigger})`);
|
||||
}
|
||||
|
||||
return checkpoint;
|
||||
} catch (error) {
|
||||
this.log(`Error checking recovery: ${(error as Error).message}`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate recovery message for context injection
|
||||
*
|
||||
* @param checkpoint - The checkpoint to format
|
||||
* @returns Formatted recovery message
|
||||
*/
|
||||
async formatRecoveryMessage(checkpoint: Checkpoint): Promise<string> {
|
||||
try {
|
||||
const { CheckpointService } = await import('../services/checkpoint-service.js');
|
||||
|
||||
const checkpointService = new CheckpointService({
|
||||
projectPath: this.projectPath,
|
||||
enableLogging: false
|
||||
});
|
||||
|
||||
return checkpointService.formatRecoveryMessage(checkpoint);
|
||||
} catch (error) {
|
||||
// Fallback to basic format
|
||||
return `# Session Recovery
|
||||
|
||||
**Checkpoint ID:** ${checkpoint.id}
|
||||
**Created:** ${checkpoint.created_at}
|
||||
**Trigger:** ${checkpoint.trigger}
|
||||
**Session:** ${checkpoint.session_id}
|
||||
|
||||
*This checkpoint was created to preserve session state.*`;
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Mutex Status
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Check if compaction is currently in progress for a directory
|
||||
*
|
||||
* @param directory - The directory to check
|
||||
* @returns true if compaction is in progress
|
||||
*/
|
||||
isCompactionInProgress(directory: string): boolean {
|
||||
return inflightCompactions.has(directory);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the number of callers queued behind an in-flight compaction
|
||||
*
|
||||
* @param directory - The directory to check
|
||||
* @returns Number of queued callers (0 if no compaction in progress)
|
||||
*/
|
||||
getCompactionQueueDepth(directory: string): number {
|
||||
return compactionQueueDepth.get(directory) ?? 0;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Private: Utility Methods
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Log a message if logging is enabled
|
||||
*/
|
||||
private log(message: string): void {
|
||||
if (this.enableLogging) {
|
||||
const timestamp = new Date().toISOString();
|
||||
console.log(`[RecoveryHandler ${timestamp}] ${message}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Factory Function
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Create a RecoveryHandler instance
|
||||
*
|
||||
* @param options - Handler options
|
||||
* @returns RecoveryHandler instance
|
||||
*/
|
||||
export function createRecoveryHandler(options: RecoveryHandlerOptions): RecoveryHandler {
|
||||
return new RecoveryHandler(options);
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Default Export
|
||||
// =============================================================================
|
||||
|
||||
export default RecoveryHandler;
|
||||
365
ccw/src/core/hooks/stop-handler.ts
Normal file
365
ccw/src/core/hooks/stop-handler.ts
Normal file
@@ -0,0 +1,365 @@
|
||||
/**
|
||||
* StopHandler - Unified stop hook handler with Soft Enforcement
|
||||
*
|
||||
* Handles Stop hook events with priority-based checking:
|
||||
* 1. context-limit: Always allow stop (deadlock prevention)
|
||||
* 2. user-abort: Respect user intent
|
||||
* 3. active-workflow: Inject continuation message
|
||||
* 4. active-mode: Inject continuation message (uses ModeRegistryService)
|
||||
*
|
||||
* Design:
|
||||
* - ALWAYS returns continue: true (Soft Enforcement)
|
||||
* - Injects continuation message instead of blocking
|
||||
* - Logs all stop events for debugging
|
||||
* - Integrates with ModeRegistryService for mode state detection
|
||||
*/
|
||||
|
||||
import { isContextLimitStop } from './context-limit-detector.js';
|
||||
import { isUserAbort, type StopContext } from './user-abort-detector.js';
|
||||
import type { ExecutionMode } from '../services/mode-registry-service.js';
|
||||
|
||||
// =============================================================================
|
||||
// Types
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Extended stop context with additional fields
|
||||
*/
|
||||
export interface ExtendedStopContext extends StopContext {
|
||||
/** Session ID */
|
||||
session_id?: string;
|
||||
/** Session ID (camelCase variant) */
|
||||
sessionId?: string;
|
||||
/** Project path */
|
||||
project_path?: string;
|
||||
/** Project path (camelCase variant) */
|
||||
projectPath?: string;
|
||||
/** Current active mode */
|
||||
active_mode?: 'analysis' | 'write' | 'review' | 'auto';
|
||||
/** Current active mode (camelCase variant) */
|
||||
activeMode?: 'analysis' | 'write' | 'review' | 'auto';
|
||||
/** Whether there's an active workflow */
|
||||
active_workflow?: boolean;
|
||||
/** Whether there's an active workflow (camelCase variant) */
|
||||
activeWorkflow?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Result of stop handling
|
||||
*/
|
||||
export interface StopResult {
|
||||
/** ALWAYS true - we never block stops */
|
||||
continue: true;
|
||||
/** Optional continuation message to inject */
|
||||
message?: string;
|
||||
/** Which handler was triggered */
|
||||
mode?: 'context-limit' | 'user-abort' | 'active-workflow' | 'active-mode' | 'none';
|
||||
/** Additional metadata */
|
||||
metadata?: {
|
||||
/** Reason for stop (from context) */
|
||||
reason?: string;
|
||||
/** Whether user requested stop */
|
||||
userRequested?: boolean;
|
||||
/** Session ID */
|
||||
sessionId?: string;
|
||||
/** Active mode if any */
|
||||
activeMode?: string;
|
||||
/** Whether workflow was active */
|
||||
activeWorkflow?: boolean;
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Options for StopHandler
|
||||
*/
|
||||
export interface StopHandlerOptions {
|
||||
/** Whether to enable logging */
|
||||
enableLogging?: boolean;
|
||||
/** Custom message for workflow continuation */
|
||||
workflowContinuationMessage?: string;
|
||||
/** Custom message for mode continuation */
|
||||
modeContinuationMessage?: string;
|
||||
/** Project path for ModeRegistryService */
|
||||
projectPath?: string;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Constants
|
||||
// =============================================================================
|
||||
|
||||
/** Default workflow continuation message */
|
||||
const DEFAULT_WORKFLOW_MESSAGE = `[WORKFLOW CONTINUATION]
|
||||
An active workflow is in progress.
|
||||
|
||||
If you intended to stop:
|
||||
- Use explicit cancellation command to exit cleanly
|
||||
- Otherwise, continue with your workflow tasks
|
||||
|
||||
`;
|
||||
|
||||
/** Default mode continuation message */
|
||||
const DEFAULT_MODE_MESSAGE = `[MODE CONTINUATION]
|
||||
An active mode is set for this session.
|
||||
|
||||
Mode: {mode}
|
||||
|
||||
Continue with your current task, or use cancellation command to exit.
|
||||
|
||||
`;
|
||||
|
||||
// =============================================================================
|
||||
// StopHandler
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Handler for Stop hook events
|
||||
*
|
||||
* This handler implements Soft Enforcement: it never blocks stops,
|
||||
* but injects continuation messages to encourage task completion.
|
||||
*/
|
||||
export class StopHandler {
|
||||
private enableLogging: boolean;
|
||||
private workflowContinuationMessage: string;
|
||||
private modeContinuationMessage: string;
|
||||
private projectPath?: string;
|
||||
|
||||
constructor(options: StopHandlerOptions = {}) {
|
||||
this.enableLogging = options.enableLogging ?? false;
|
||||
this.workflowContinuationMessage =
|
||||
options.workflowContinuationMessage ?? DEFAULT_WORKFLOW_MESSAGE;
|
||||
this.modeContinuationMessage =
|
||||
options.modeContinuationMessage ?? DEFAULT_MODE_MESSAGE;
|
||||
this.projectPath = options.projectPath;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Main Handler
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Handle a stop event
|
||||
*
|
||||
* Priority order:
|
||||
* 1. context-limit: Always allow (deadlock prevention)
|
||||
* 2. user-abort: Respect user intent
|
||||
* 3. active-workflow: Inject continuation message
|
||||
* 4. active-mode: Inject continuation message (via ModeRegistryService)
|
||||
*
|
||||
* @param context - Stop context from hook event
|
||||
* @returns Stop result (always continue: true)
|
||||
*/
|
||||
async handleStop(context?: ExtendedStopContext): Promise<StopResult> {
|
||||
this.log('Handling stop event...');
|
||||
|
||||
// Extract common fields with both naming conventions
|
||||
const sessionId = context?.session_id ?? context?.sessionId;
|
||||
const activeMode = context?.active_mode ?? context?.activeMode;
|
||||
const activeWorkflow = context?.active_workflow ?? context?.activeWorkflow;
|
||||
const userRequested = context?.user_requested ?? context?.userRequested;
|
||||
|
||||
// Get stop reason
|
||||
const reason = context?.stop_reason ?? context?.stopReason ?? '';
|
||||
const endTurnReason = context?.end_turn_reason ?? context?.endTurnReason ?? '';
|
||||
const fullReason = `${reason} ${endTurnReason}`.trim();
|
||||
|
||||
this.log(`Context: sessionId=${sessionId}, reason="${fullReason}", userRequested=${userRequested}`);
|
||||
|
||||
// Priority 1: Context Limit - CRITICAL: Never block
|
||||
// Blocking context-limit stops causes deadlock (can't compact if can't stop)
|
||||
if (isContextLimitStop(context)) {
|
||||
this.log('Context limit detected - allowing stop');
|
||||
return {
|
||||
continue: true,
|
||||
mode: 'context-limit',
|
||||
metadata: {
|
||||
reason: fullReason,
|
||||
sessionId,
|
||||
userRequested
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// Priority 2: User Abort - Respect user intent
|
||||
if (isUserAbort(context)) {
|
||||
this.log('User abort detected - respecting user intent');
|
||||
return {
|
||||
continue: true,
|
||||
mode: 'user-abort',
|
||||
metadata: {
|
||||
reason: fullReason,
|
||||
userRequested: true,
|
||||
sessionId
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// Priority 3: Active Workflow - Inject continuation message
|
||||
if (activeWorkflow) {
|
||||
this.log('Active workflow detected - injecting continuation message');
|
||||
return {
|
||||
continue: true,
|
||||
message: this.workflowContinuationMessage,
|
||||
mode: 'active-workflow',
|
||||
metadata: {
|
||||
reason: fullReason,
|
||||
sessionId,
|
||||
activeWorkflow: true
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// Priority 4: Active Mode - Check via ModeRegistryService
|
||||
if (this.projectPath && sessionId) {
|
||||
try {
|
||||
const { ModeRegistryService } = await import('../services/mode-registry-service.js');
|
||||
const modeRegistry = new ModeRegistryService({
|
||||
projectPath: this.projectPath,
|
||||
enableLogging: this.enableLogging
|
||||
});
|
||||
|
||||
const activeModes = modeRegistry.getActiveModes(sessionId);
|
||||
if (activeModes.length > 0) {
|
||||
const primaryMode = activeModes[0];
|
||||
const modeConfig = (await import('../services/mode-registry-service.js')).MODE_CONFIGS[primaryMode];
|
||||
const modeName = modeConfig?.name ?? primaryMode;
|
||||
|
||||
this.log(`Active mode "${modeName}" detected via ModeRegistryService - injecting continuation message`);
|
||||
const message = this.modeContinuationMessage.replace('{mode}', modeName);
|
||||
return {
|
||||
continue: true,
|
||||
message,
|
||||
mode: 'active-mode',
|
||||
metadata: {
|
||||
reason: fullReason,
|
||||
sessionId,
|
||||
activeMode: primaryMode
|
||||
}
|
||||
};
|
||||
}
|
||||
} catch (error) {
|
||||
this.log(`Error checking mode registry: ${(error as Error).message}`);
|
||||
// Fall through to check context-based active mode
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback: Check active mode from context
|
||||
if (activeMode) {
|
||||
this.log(`Active mode "${activeMode}" detected from context - injecting continuation message`);
|
||||
const message = this.modeContinuationMessage.replace('{mode}', String(activeMode));
|
||||
return {
|
||||
continue: true,
|
||||
message,
|
||||
mode: 'active-mode',
|
||||
metadata: {
|
||||
reason: fullReason,
|
||||
sessionId,
|
||||
activeMode: String(activeMode)
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// Default: No special handling needed
|
||||
this.log('No special handling needed - allowing stop');
|
||||
return {
|
||||
continue: true,
|
||||
mode: 'none',
|
||||
metadata: {
|
||||
reason: fullReason,
|
||||
sessionId,
|
||||
userRequested
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Utility Methods
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Check if a stop should trigger continuation message
|
||||
*
|
||||
* @param context - Stop context
|
||||
* @returns true if continuation message should be injected
|
||||
*/
|
||||
async shouldInjectContinuation(context?: ExtendedStopContext): Promise<boolean> {
|
||||
// Context limit and user abort don't get continuation
|
||||
if (isContextLimitStop(context) || isUserAbort(context)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Active workflow gets continuation
|
||||
const activeWorkflow = context?.active_workflow ?? context?.activeWorkflow;
|
||||
if (activeWorkflow) {
|
||||
return true;
|
||||
}
|
||||
|
||||
// Check via ModeRegistryService if projectPath is available
|
||||
const sessionId = context?.session_id ?? context?.sessionId;
|
||||
if (this.projectPath && sessionId) {
|
||||
try {
|
||||
const { ModeRegistryService } = await import('../services/mode-registry-service.js');
|
||||
const modeRegistry = new ModeRegistryService({
|
||||
projectPath: this.projectPath,
|
||||
enableLogging: false
|
||||
});
|
||||
|
||||
if (modeRegistry.isAnyModeActive(sessionId)) {
|
||||
return true;
|
||||
}
|
||||
} catch {
|
||||
// Fall through to context-based check
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback: Check active mode from context
|
||||
const activeMode = context?.active_mode ?? context?.activeMode;
|
||||
return Boolean(activeMode);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the stop reason from context
|
||||
*
|
||||
* @param context - Stop context
|
||||
* @returns Normalized stop reason
|
||||
*/
|
||||
getStopReason(context?: ExtendedStopContext): string {
|
||||
const reason = context?.stop_reason ?? context?.stopReason ?? '';
|
||||
const endTurnReason = context?.end_turn_reason ?? context?.endTurnReason ?? '';
|
||||
return `${reason} ${endTurnReason}`.trim() || 'unknown';
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Private: Utility Methods
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Log a message if logging is enabled
|
||||
*/
|
||||
private log(message: string): void {
|
||||
if (this.enableLogging) {
|
||||
const timestamp = new Date().toISOString();
|
||||
console.log(`[StopHandler ${timestamp}] ${message}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Factory Function
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Create a StopHandler instance
|
||||
*
|
||||
* @param options - Handler options
|
||||
* @returns StopHandler instance
|
||||
*/
|
||||
export function createStopHandler(options?: StopHandlerOptions): StopHandler {
|
||||
return new StopHandler(options);
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Default Export
|
||||
// =============================================================================
|
||||
|
||||
/** Default StopHandler instance */
|
||||
export const defaultStopHandler = new StopHandler();
|
||||
194
ccw/src/core/hooks/user-abort-detector.ts
Normal file
194
ccw/src/core/hooks/user-abort-detector.ts
Normal file
@@ -0,0 +1,194 @@
|
||||
/**
|
||||
* UserAbortDetector - Detects user-initiated abort stops
|
||||
*
|
||||
* Detects if a stop was due to user abort (not natural completion).
|
||||
* This allows hooks to gracefully handle user-initiated stops differently
|
||||
* from automatic or system-initiated stops.
|
||||
*
|
||||
* NOTE: Per official Anthropic docs, the Stop hook "Does not run if
|
||||
* the stoppage occurred due to a user interrupt." This means this
|
||||
* detector may never receive user-abort contexts in practice.
|
||||
* It is kept as defensive code in case the behavior changes.
|
||||
*/
|
||||
|
||||
import type { StopContext } from './context-limit-detector.js';
|
||||
|
||||
// Re-export StopContext for convenience
|
||||
export type { StopContext } from './context-limit-detector.js';
|
||||
|
||||
/**
|
||||
* Patterns that indicate user abort (exact match)
|
||||
*
|
||||
* These are short generic words that need exact matching to avoid
|
||||
* false positives with substring matching (e.g., "cancel" in "cancelled_order").
|
||||
*/
|
||||
export const USER_ABORT_EXACT_PATTERNS: readonly string[] = [
|
||||
'aborted',
|
||||
'abort',
|
||||
'cancel',
|
||||
'interrupt'
|
||||
] as const;
|
||||
|
||||
/**
|
||||
* Patterns that indicate user abort (substring match)
|
||||
*
|
||||
* These are compound words that are safe for substring matching
|
||||
* because they are unlikely to appear as parts of other words.
|
||||
*/
|
||||
export const USER_ABORT_SUBSTRING_PATTERNS: readonly string[] = [
|
||||
'user_cancel',
|
||||
'user_interrupt',
|
||||
'ctrl_c',
|
||||
'manual_stop'
|
||||
] as const;
|
||||
|
||||
/**
|
||||
* All user abort patterns combined
|
||||
*/
|
||||
export const USER_ABORT_PATTERNS: readonly string[] = [
|
||||
...USER_ABORT_EXACT_PATTERNS,
|
||||
...USER_ABORT_SUBSTRING_PATTERNS
|
||||
] as const;
|
||||
|
||||
/**
|
||||
* Check if a reason matches exact abort patterns
|
||||
*
|
||||
* @param reason - The reason string to check (should be lowercase)
|
||||
* @returns true if the reason exactly matches an abort pattern
|
||||
*/
|
||||
function matchesExactPattern(reason: string): boolean {
|
||||
return USER_ABORT_EXACT_PATTERNS.some(pattern => reason === pattern);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a reason matches substring abort patterns
|
||||
*
|
||||
* @param reason - The reason string to check (should be lowercase)
|
||||
* @returns true if the reason contains a substring abort pattern
|
||||
*/
|
||||
function matchesSubstringPattern(reason: string): boolean {
|
||||
return USER_ABORT_SUBSTRING_PATTERNS.some(pattern => reason.includes(pattern));
|
||||
}
|
||||
|
||||
/**
|
||||
* Detect if stop was due to user abort (not natural completion)
|
||||
*
|
||||
* WARNING: These patterns are ASSUMED based on common conventions.
|
||||
* As of 2025-01, Anthropic's Stop hook input schema does not document
|
||||
* the exact stop_reason values. The patterns below are educated guesses:
|
||||
*
|
||||
* - user_cancel, user_interrupt: Likely user-initiated via UI
|
||||
* - ctrl_c: Terminal interrupt (Ctrl+C)
|
||||
* - manual_stop: Explicit stop button
|
||||
* - abort, cancel, interrupt: Generic abort patterns
|
||||
*
|
||||
* If the detector fails to detect user aborts correctly, these patterns
|
||||
* should be updated based on observed Claude Code behavior.
|
||||
*
|
||||
* @param context - The stop context from the hook event
|
||||
* @returns true if the stop was due to user abort
|
||||
*/
|
||||
export function isUserAbort(context?: StopContext): boolean {
|
||||
if (!context) return false;
|
||||
|
||||
// User explicitly requested stop (supports both camelCase and snake_case)
|
||||
if (context.user_requested === true || context.userRequested === true) {
|
||||
return true;
|
||||
}
|
||||
|
||||
// Get reason from both field naming conventions
|
||||
const reason = (context.stop_reason ?? context.stopReason ?? '').toLowerCase();
|
||||
|
||||
// Check exact patterns first (short words that could cause false positives)
|
||||
if (matchesExactPattern(reason)) {
|
||||
return true;
|
||||
}
|
||||
|
||||
// Then check substring patterns (compound words safe for includes)
|
||||
if (matchesSubstringPattern(reason)) {
|
||||
return true;
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the matching user abort pattern if any
|
||||
*
|
||||
* @param context - The stop context from the hook event
|
||||
* @returns The matching pattern or null if no match
|
||||
*/
|
||||
export function getMatchingAbortPattern(context?: StopContext): string | null {
|
||||
if (!context) return null;
|
||||
|
||||
// Check explicit user_requested flag first
|
||||
if (context.user_requested === true || context.userRequested === true) {
|
||||
return 'user_requested';
|
||||
}
|
||||
|
||||
const reason = (context.stop_reason ?? context.stopReason ?? '').toLowerCase();
|
||||
|
||||
// Check exact patterns
|
||||
for (const pattern of USER_ABORT_EXACT_PATTERNS) {
|
||||
if (reason === pattern) {
|
||||
return pattern;
|
||||
}
|
||||
}
|
||||
|
||||
// Check substring patterns
|
||||
for (const pattern of USER_ABORT_SUBSTRING_PATTERNS) {
|
||||
if (reason.includes(pattern)) {
|
||||
return pattern;
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all matching user abort patterns
|
||||
*
|
||||
* @param context - The stop context from the hook event
|
||||
* @returns Array of matching patterns (may be empty)
|
||||
*/
|
||||
export function getAllMatchingAbortPatterns(context?: StopContext): string[] {
|
||||
if (!context) return [];
|
||||
|
||||
const matches: string[] = [];
|
||||
|
||||
// Check explicit user_requested flag first
|
||||
if (context.user_requested === true || context.userRequested === true) {
|
||||
matches.push('user_requested');
|
||||
}
|
||||
|
||||
const reason = (context.stop_reason ?? context.stopReason ?? '').toLowerCase();
|
||||
|
||||
// Check exact patterns
|
||||
for (const pattern of USER_ABORT_EXACT_PATTERNS) {
|
||||
if (reason === pattern) {
|
||||
matches.push(pattern);
|
||||
}
|
||||
}
|
||||
|
||||
// Check substring patterns
|
||||
for (const pattern of USER_ABORT_SUBSTRING_PATTERNS) {
|
||||
if (reason.includes(pattern)) {
|
||||
matches.push(pattern);
|
||||
}
|
||||
}
|
||||
|
||||
return Array.from(new Set(matches)); // Remove duplicates
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a stop should allow continuation
|
||||
*
|
||||
* User aborts should NOT force continuation - if the user explicitly
|
||||
* stopped the session, we should respect that decision.
|
||||
*
|
||||
* @param context - The stop context from the hook event
|
||||
* @returns true if continuation should be allowed (not a user abort)
|
||||
*/
|
||||
export function shouldAllowContinuation(context?: StopContext): boolean {
|
||||
return !isUserAbort(context);
|
||||
}
|
||||
366
ccw/src/core/mode-workflow-map.ts
Normal file
366
ccw/src/core/mode-workflow-map.ts
Normal file
@@ -0,0 +1,366 @@
|
||||
/**
|
||||
* ModeWorkflowMap - Mode to Workflow Mapping
|
||||
*
|
||||
* Maps execution modes to their corresponding workflow types and provides
|
||||
* workflow activation configuration for each mode.
|
||||
*
|
||||
* Mode -> Workflow Mappings:
|
||||
* - autopilot -> unified-execute-with-file (autonomous multi-step execution)
|
||||
* - ralph -> team-planex (research and analysis)
|
||||
* - ultrawork -> test-fix (ultra-focused work with test feedback)
|
||||
* - swarm -> parallel-agents (multi-agent parallel execution)
|
||||
* - pipeline -> lite-plan (sequential pipeline execution)
|
||||
* - team -> team-iterdev (team collaboration)
|
||||
* - ultraqa -> test-fix (QA-focused test cycles)
|
||||
*/
|
||||
|
||||
import { ExecutionMode, MODE_CONFIGS } from './services/mode-registry-service.js';
|
||||
|
||||
// =============================================================================
|
||||
// Types
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Workflow types supported by the system
|
||||
*/
|
||||
export type WorkflowType =
|
||||
| 'unified-execute-with-file'
|
||||
| 'team-planex'
|
||||
| 'test-fix'
|
||||
| 'parallel-agents'
|
||||
| 'lite-plan'
|
||||
| 'team-iterdev';
|
||||
|
||||
/**
|
||||
* Configuration for workflow activation
|
||||
*/
|
||||
export interface WorkflowActivationConfig {
|
||||
/** The workflow type to activate */
|
||||
workflowType: WorkflowType;
|
||||
/** Whether this workflow requires session persistence */
|
||||
requiresPersistence: boolean;
|
||||
/** Default execution mode for the workflow */
|
||||
defaultExecutionMode: 'analysis' | 'write' | 'auto';
|
||||
/** Whether parallel execution is supported */
|
||||
supportsParallel: boolean;
|
||||
/** Maximum concurrent tasks (for parallel workflows) */
|
||||
maxConcurrentTasks?: number;
|
||||
/** Description of the workflow */
|
||||
description: string;
|
||||
/** Required context keys for activation */
|
||||
requiredContext?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Context passed during workflow activation
|
||||
*/
|
||||
export interface WorkflowActivationContext {
|
||||
/** Session ID for the workflow */
|
||||
sessionId: string;
|
||||
/** Project root path */
|
||||
projectPath: string;
|
||||
/** User prompt or task description */
|
||||
prompt?: string;
|
||||
/** Additional context data */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Result of workflow activation
|
||||
*/
|
||||
export interface WorkflowActivationResult {
|
||||
/** Whether activation was successful */
|
||||
success: boolean;
|
||||
/** The session ID (may be new or existing) */
|
||||
sessionId: string;
|
||||
/** The activated workflow type */
|
||||
workflowType: WorkflowType;
|
||||
/** Error message if activation failed */
|
||||
error?: string;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Constants
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Mode to Workflow mapping configuration
|
||||
*
|
||||
* Each mode maps to a specific workflow type with its activation config.
|
||||
*/
|
||||
export const MODE_WORKFLOW_MAP: Record<ExecutionMode, WorkflowActivationConfig> = {
|
||||
/**
|
||||
* Autopilot Mode -> unified-execute-with-file
|
||||
* Autonomous execution of multi-step tasks with file-based state persistence.
|
||||
*/
|
||||
autopilot: {
|
||||
workflowType: 'unified-execute-with-file',
|
||||
requiresPersistence: true,
|
||||
defaultExecutionMode: 'write',
|
||||
supportsParallel: false,
|
||||
description: 'Autonomous multi-step task execution with file-based state',
|
||||
requiredContext: ['prompt']
|
||||
},
|
||||
|
||||
/**
|
||||
* Ralph Mode -> team-planex
|
||||
* Research and Analysis Learning Pattern Handler for iterative exploration.
|
||||
*/
|
||||
ralph: {
|
||||
workflowType: 'team-planex',
|
||||
requiresPersistence: true,
|
||||
defaultExecutionMode: 'analysis',
|
||||
supportsParallel: false,
|
||||
description: 'Research and analysis pattern handler for iterative exploration'
|
||||
},
|
||||
|
||||
/**
|
||||
* Ultrawork Mode -> test-fix
|
||||
* Ultra-focused work mode with test-feedback loop.
|
||||
*/
|
||||
ultrawork: {
|
||||
workflowType: 'test-fix',
|
||||
requiresPersistence: true,
|
||||
defaultExecutionMode: 'write',
|
||||
supportsParallel: false,
|
||||
description: 'Ultra-focused work mode with test-driven feedback loop'
|
||||
},
|
||||
|
||||
/**
|
||||
* Swarm Mode -> parallel-agents
|
||||
* Multi-agent parallel execution for distributed task processing.
|
||||
*/
|
||||
swarm: {
|
||||
workflowType: 'parallel-agents',
|
||||
requiresPersistence: true,
|
||||
defaultExecutionMode: 'write',
|
||||
supportsParallel: true,
|
||||
maxConcurrentTasks: 5,
|
||||
description: 'Multi-agent parallel execution for distributed tasks'
|
||||
},
|
||||
|
||||
/**
|
||||
* Pipeline Mode -> lite-plan
|
||||
* Sequential pipeline execution for stage-based workflows.
|
||||
*/
|
||||
pipeline: {
|
||||
workflowType: 'lite-plan',
|
||||
requiresPersistence: true,
|
||||
defaultExecutionMode: 'write',
|
||||
supportsParallel: false,
|
||||
description: 'Sequential pipeline execution for stage-based workflows'
|
||||
},
|
||||
|
||||
/**
|
||||
* Team Mode -> team-iterdev
|
||||
* Team collaboration mode for iterative development.
|
||||
*/
|
||||
team: {
|
||||
workflowType: 'team-iterdev',
|
||||
requiresPersistence: true,
|
||||
defaultExecutionMode: 'write',
|
||||
supportsParallel: true,
|
||||
maxConcurrentTasks: 3,
|
||||
description: 'Team collaboration mode for iterative development'
|
||||
},
|
||||
|
||||
/**
|
||||
* UltraQA Mode -> test-fix
|
||||
* QA-focused test cycles with iterative quality improvements.
|
||||
*/
|
||||
ultraqa: {
|
||||
workflowType: 'test-fix',
|
||||
requiresPersistence: true,
|
||||
defaultExecutionMode: 'write',
|
||||
supportsParallel: false,
|
||||
description: 'QA-focused test cycles with iterative quality improvements'
|
||||
}
|
||||
};
|
||||
|
||||
// =============================================================================
|
||||
// Helper Functions
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Get the workflow type for a given execution mode
|
||||
*
|
||||
* @param mode - The execution mode
|
||||
* @returns The corresponding workflow type, or undefined if not found
|
||||
*/
|
||||
export function getWorkflowForMode(mode: ExecutionMode): WorkflowType | undefined {
|
||||
const config = MODE_WORKFLOW_MAP[mode];
|
||||
return config?.workflowType;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the activation configuration for a given execution mode
|
||||
*
|
||||
* @param mode - The execution mode
|
||||
* @returns The activation configuration, or undefined if not found
|
||||
*/
|
||||
export function getActivationConfig(mode: ExecutionMode): WorkflowActivationConfig | undefined {
|
||||
return MODE_WORKFLOW_MAP[mode];
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all modes that map to a specific workflow type
|
||||
*
|
||||
* @param workflowType - The workflow type to filter by
|
||||
* @returns Array of execution modes that use this workflow
|
||||
*/
|
||||
export function getModesForWorkflow(workflowType: WorkflowType): ExecutionMode[] {
|
||||
return (Object.entries(MODE_WORKFLOW_MAP) as [ExecutionMode, WorkflowActivationConfig][])
|
||||
.filter(([, config]) => config.workflowType === workflowType)
|
||||
.map(([mode]) => mode);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a mode supports parallel execution
|
||||
*
|
||||
* @param mode - The execution mode
|
||||
* @returns true if the mode supports parallel execution
|
||||
*/
|
||||
export function isParallelMode(mode: ExecutionMode): boolean {
|
||||
const config = MODE_WORKFLOW_MAP[mode];
|
||||
return config?.supportsParallel ?? false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the maximum concurrent tasks for a parallel mode
|
||||
*
|
||||
* @param mode - The execution mode
|
||||
* @returns Maximum concurrent tasks, or 1 if not a parallel mode
|
||||
*/
|
||||
export function getMaxConcurrentTasks(mode: ExecutionMode): number {
|
||||
const config = MODE_WORKFLOW_MAP[mode];
|
||||
if (!config?.supportsParallel) {
|
||||
return 1;
|
||||
}
|
||||
return config.maxConcurrentTasks ?? 3;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate that required context is present for mode activation
|
||||
*
|
||||
* @param mode - The execution mode
|
||||
* @param context - The activation context
|
||||
* @returns Object with valid flag and missing keys if any
|
||||
*/
|
||||
export function validateActivationContext(
|
||||
mode: ExecutionMode,
|
||||
context: WorkflowActivationContext
|
||||
): { valid: boolean; missingKeys: string[] } {
|
||||
const config = MODE_WORKFLOW_MAP[mode];
|
||||
const requiredKeys = config?.requiredContext ?? [];
|
||||
const missingKeys: string[] = [];
|
||||
|
||||
for (const key of requiredKeys) {
|
||||
if (key === 'prompt' && !context.prompt) {
|
||||
missingKeys.push(key);
|
||||
} else if (key === 'sessionId' && !context.sessionId) {
|
||||
missingKeys.push(key);
|
||||
} else if (key === 'projectPath' && !context.projectPath) {
|
||||
missingKeys.push(key);
|
||||
} else if (key.startsWith('metadata.') && context.metadata) {
|
||||
const metaKey = key.substring('metadata.'.length);
|
||||
if (!(metaKey in context.metadata)) {
|
||||
missingKeys.push(key);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
valid: missingKeys.length === 0,
|
||||
missingKeys
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Activate a workflow for a given mode
|
||||
*
|
||||
* This function creates the necessary session state and returns
|
||||
* activation result. The actual workflow execution is handled
|
||||
* by the respective workflow handlers.
|
||||
*
|
||||
* @param mode - The execution mode to activate
|
||||
* @param context - The activation context
|
||||
* @returns Promise resolving to activation result
|
||||
*/
|
||||
export async function activateWorkflowForMode(
|
||||
mode: ExecutionMode,
|
||||
context: WorkflowActivationContext
|
||||
): Promise<WorkflowActivationResult> {
|
||||
const config = MODE_WORKFLOW_MAP[mode];
|
||||
const modeConfig = MODE_CONFIGS[mode];
|
||||
|
||||
// Validate mode exists
|
||||
if (!config) {
|
||||
return {
|
||||
success: false,
|
||||
sessionId: context.sessionId,
|
||||
workflowType: 'unified-execute-with-file', // Default fallback
|
||||
error: `Unknown mode: ${mode}`
|
||||
};
|
||||
}
|
||||
|
||||
// Validate required context
|
||||
const validation = validateActivationContext(mode, context);
|
||||
if (!validation.valid) {
|
||||
return {
|
||||
success: false,
|
||||
sessionId: context.sessionId,
|
||||
workflowType: config.workflowType,
|
||||
error: `Missing required context: ${validation.missingKeys.join(', ')}`
|
||||
};
|
||||
}
|
||||
|
||||
// Validate session ID
|
||||
if (!context.sessionId) {
|
||||
return {
|
||||
success: false,
|
||||
sessionId: '',
|
||||
workflowType: config.workflowType,
|
||||
error: 'Session ID is required for workflow activation'
|
||||
};
|
||||
}
|
||||
|
||||
// Return success result
|
||||
// Note: Actual session state persistence is handled by ModeRegistryService
|
||||
return {
|
||||
success: true,
|
||||
sessionId: context.sessionId,
|
||||
workflowType: config.workflowType
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a human-readable description for a mode's workflow
|
||||
*
|
||||
* @param mode - The execution mode
|
||||
* @returns Description string
|
||||
*/
|
||||
export function getWorkflowDescription(mode: ExecutionMode): string {
|
||||
const config = MODE_WORKFLOW_MAP[mode];
|
||||
const modeConfig = MODE_CONFIGS[mode];
|
||||
return config?.description ?? modeConfig?.description ?? `Workflow for ${mode} mode`;
|
||||
}
|
||||
|
||||
/**
|
||||
* List all available mode-to-workflow mappings
|
||||
*
|
||||
* @returns Array of mode-workflow mapping entries
|
||||
*/
|
||||
export function listModeWorkflowMappings(): Array<{
|
||||
mode: ExecutionMode;
|
||||
workflowType: WorkflowType;
|
||||
description: string;
|
||||
supportsParallel: boolean;
|
||||
}> {
|
||||
return (Object.entries(MODE_WORKFLOW_MAP) as [ExecutionMode, WorkflowActivationConfig][])
|
||||
.map(([mode, config]) => ({
|
||||
mode,
|
||||
workflowType: config.workflowType,
|
||||
description: config.description,
|
||||
supportsParallel: config.supportsParallel
|
||||
}));
|
||||
}
|
||||
@@ -1,6 +1,26 @@
|
||||
/**
|
||||
* Hooks Routes Module
|
||||
* Handles all hooks-related API endpoints
|
||||
*
|
||||
* ## API Endpoints
|
||||
*
|
||||
* ### Active Endpoints
|
||||
* - POST /api/hook - Main hook endpoint for Claude Code notifications
|
||||
* - Handles: session-start, context, CLI events, A2UI surfaces
|
||||
* - POST /api/hook/ccw-exec - Execute CCW CLI commands and parse output
|
||||
* - GET /api/hooks - Get hooks configuration from global and project settings
|
||||
* - POST /api/hooks - Save a hook to settings
|
||||
* - DELETE /api/hooks - Delete a hook from settings
|
||||
*
|
||||
* ### Deprecated Endpoints (will be removed in v2.0.0)
|
||||
* - POST /api/hook/session-context - Use `ccw hook session-context --stdin` instead
|
||||
* - POST /api/hook/ccw-status - Use /api/hook/ccw-exec with command=parse-status
|
||||
*
|
||||
* ## Service Layer
|
||||
* All endpoints use unified services:
|
||||
* - HookContextService: Context generation for session-start and per-prompt hooks
|
||||
* - SessionStateService: Session state tracking and persistence
|
||||
* - SessionEndService: Background task management for session-end events
|
||||
*/
|
||||
import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
|
||||
import { join, dirname } from 'path';
|
||||
@@ -235,26 +255,27 @@ export async function handleHooksRoutes(ctx: HooksRouteContext): Promise<boolean
|
||||
if (type === 'session-start' || type === 'context') {
|
||||
try {
|
||||
const projectPath = url.searchParams.get('path') || initialPath;
|
||||
const { SessionClusteringService } = await import('../session-clustering-service.js');
|
||||
const clusteringService = new SessionClusteringService(projectPath);
|
||||
|
||||
// Use HookContextService for unified context generation
|
||||
const { HookContextService } = await import('../services/hook-context-service.js');
|
||||
const contextService = new HookContextService({ projectPath });
|
||||
|
||||
const format = url.searchParams.get('format') || 'markdown';
|
||||
const prompt = typeof extraData.prompt === 'string' ? extraData.prompt : undefined;
|
||||
|
||||
// Pass type and prompt to getProgressiveIndex
|
||||
// session-start: returns recent sessions by time
|
||||
// context: returns intent-matched sessions based on prompt
|
||||
const index = await clusteringService.getProgressiveIndex({
|
||||
type: type as 'session-start' | 'context',
|
||||
sessionId: resolvedSessionId,
|
||||
prompt: typeof extraData.prompt === 'string' ? extraData.prompt : undefined // Pass user prompt for intent matching
|
||||
// Build context using the service
|
||||
const result = await contextService.buildPromptContext({
|
||||
sessionId: resolvedSessionId || '',
|
||||
prompt,
|
||||
projectId: projectPath
|
||||
});
|
||||
|
||||
// Return context directly
|
||||
return {
|
||||
success: true,
|
||||
type: 'context',
|
||||
type: result.type,
|
||||
format,
|
||||
content: index,
|
||||
content: result.content,
|
||||
sessionId: resolvedSessionId
|
||||
};
|
||||
} catch (error) {
|
||||
@@ -336,84 +357,56 @@ export async function handleHooksRoutes(ctx: HooksRouteContext): Promise<boolean
|
||||
}
|
||||
|
||||
// API: Unified Session Context endpoint (Progressive Disclosure)
|
||||
// DEPRECATED: Use CLI command `ccw hook session-context --stdin` instead.
|
||||
// This endpoint now uses file-based state (shared with CLI) for consistency.
|
||||
// @DEPRECATED - This endpoint is deprecated and will be removed in a future version.
|
||||
// Migration: Use CLI command `ccw hook session-context --stdin` instead.
|
||||
// This endpoint now uses HookContextService for consistency with CLI.
|
||||
// - First prompt: returns cluster-based session overview
|
||||
// - Subsequent prompts: returns intent-matched sessions based on prompt
|
||||
if (pathname === '/api/hook/session-context' && req.method === 'POST') {
|
||||
// Add deprecation warning header
|
||||
res.setHeader('X-Deprecated', 'true');
|
||||
res.setHeader('X-Deprecation-Message', 'Use CLI command "ccw hook session-context --stdin" instead. This endpoint will be removed in v2.0.0');
|
||||
res.setHeader('X-Migration-Guide', 'https://github.com/ccw-project/ccw/blob/main/docs/migration-hooks.md#session-context');
|
||||
|
||||
handlePostRequest(req, res, async (body) => {
|
||||
// Log deprecation warning
|
||||
console.warn('[DEPRECATED] /api/hook/session-context is deprecated. Use "ccw hook session-context --stdin" instead.');
|
||||
|
||||
const { sessionId, prompt } = body as { sessionId?: string; prompt?: string };
|
||||
|
||||
if (!sessionId) {
|
||||
return {
|
||||
success: true,
|
||||
content: '',
|
||||
error: 'sessionId is required'
|
||||
error: 'sessionId is required',
|
||||
_deprecated: true,
|
||||
_migration: 'Use "ccw hook session-context --stdin"'
|
||||
};
|
||||
}
|
||||
|
||||
try {
|
||||
const projectPath = url.searchParams.get('path') || initialPath;
|
||||
const { SessionClusteringService } = await import('../session-clustering-service.js');
|
||||
const clusteringService = new SessionClusteringService(projectPath);
|
||||
|
||||
// Use file-based session state (shared with CLI hook.ts)
|
||||
const sessionStateDir = join(homedir(), '.claude', '.ccw-sessions');
|
||||
const sessionStateFile = join(sessionStateDir, `session-${sessionId}.json`);
|
||||
|
||||
let existingState: { firstLoad: string; loadCount: number; lastPrompt?: string } | null = null;
|
||||
if (existsSync(sessionStateFile)) {
|
||||
try {
|
||||
existingState = JSON.parse(readFileSync(sessionStateFile, 'utf-8'));
|
||||
} catch {
|
||||
existingState = null;
|
||||
}
|
||||
}
|
||||
|
||||
const isFirstPrompt = !existingState;
|
||||
// Use HookContextService for unified context generation
|
||||
const { HookContextService } = await import('../services/hook-context-service.js');
|
||||
const contextService = new HookContextService({ projectPath });
|
||||
|
||||
// Update session state (file-based)
|
||||
const newState = isFirstPrompt
|
||||
? { firstLoad: new Date().toISOString(), loadCount: 1, lastPrompt: prompt }
|
||||
: { ...existingState!, loadCount: existingState!.loadCount + 1, lastPrompt: prompt };
|
||||
|
||||
if (!existsSync(sessionStateDir)) {
|
||||
mkdirSync(sessionStateDir, { recursive: true });
|
||||
}
|
||||
writeFileSync(sessionStateFile, JSON.stringify(newState, null, 2));
|
||||
|
||||
// Determine which type of context to return
|
||||
let contextType: 'session-start' | 'context';
|
||||
let content: string;
|
||||
|
||||
if (isFirstPrompt) {
|
||||
// First prompt: return session overview with clusters
|
||||
contextType = 'session-start';
|
||||
content = await clusteringService.getProgressiveIndex({
|
||||
type: 'session-start',
|
||||
sessionId
|
||||
});
|
||||
} else if (prompt && prompt.trim().length > 0) {
|
||||
// Subsequent prompts with content: return intent-matched sessions
|
||||
contextType = 'context';
|
||||
content = await clusteringService.getProgressiveIndex({
|
||||
type: 'context',
|
||||
sessionId,
|
||||
prompt
|
||||
});
|
||||
} else {
|
||||
// Subsequent prompts without content: return minimal context
|
||||
contextType = 'context';
|
||||
content = ''; // No context needed for empty prompts
|
||||
}
|
||||
// Build context using the service
|
||||
const result = await contextService.buildPromptContext({
|
||||
sessionId,
|
||||
prompt,
|
||||
projectId: projectPath
|
||||
});
|
||||
|
||||
return {
|
||||
success: true,
|
||||
type: contextType,
|
||||
isFirstPrompt,
|
||||
loadCount: newState.loadCount,
|
||||
content,
|
||||
sessionId
|
||||
type: result.type,
|
||||
isFirstPrompt: result.isFirstPrompt,
|
||||
loadCount: result.state.loadCount,
|
||||
content: result.content,
|
||||
sessionId,
|
||||
_deprecated: true,
|
||||
_migration: 'Use "ccw hook session-context --stdin"'
|
||||
};
|
||||
} catch (error) {
|
||||
console.error('[Hooks] Failed to generate session context:', error);
|
||||
@@ -421,7 +414,9 @@ export async function handleHooksRoutes(ctx: HooksRouteContext): Promise<boolean
|
||||
success: true,
|
||||
content: '',
|
||||
sessionId,
|
||||
error: (error as Error).message
|
||||
error: (error as Error).message,
|
||||
_deprecated: true,
|
||||
_migration: 'Use "ccw hook session-context --stdin"'
|
||||
};
|
||||
}
|
||||
});
|
||||
@@ -474,8 +469,16 @@ export async function handleHooksRoutes(ctx: HooksRouteContext): Promise<boolean
|
||||
return true;
|
||||
}
|
||||
|
||||
// API: Parse CCW status.json and return formatted status (fallback)
|
||||
// API: Parse CCW status.json and return formatted status
|
||||
// @DEPRECATED - Use /api/hook/ccw-exec with command=parse-status instead.
|
||||
// This endpoint is kept for backward compatibility but will be removed.
|
||||
if (pathname === '/api/hook/ccw-status' && req.method === 'POST') {
|
||||
// Add deprecation warning header
|
||||
res.setHeader('X-Deprecated', 'true');
|
||||
res.setHeader('X-Deprecation-Message', 'Use /api/hook/ccw-exec with command=parse-status instead. This endpoint will be removed in v2.0.0');
|
||||
|
||||
console.warn('[DEPRECATED] /api/hook/ccw-status is deprecated. Use /api/hook/ccw-exec instead.');
|
||||
|
||||
handlePostRequest(req, res, async (body) => {
|
||||
if (typeof body !== 'object' || body === null) {
|
||||
return { error: 'Invalid request body', status: 400 };
|
||||
@@ -487,51 +490,30 @@ export async function handleHooksRoutes(ctx: HooksRouteContext): Promise<boolean
|
||||
return { error: 'filePath is required', status: 400 };
|
||||
}
|
||||
|
||||
// Check if this is a CCW status.json file
|
||||
if (!filePath.includes('status.json') ||
|
||||
!filePath.match(/\.(ccw|ccw-coordinator|ccw-debug)\//)) {
|
||||
return { success: false, message: 'Not a CCW status file' };
|
||||
}
|
||||
|
||||
// Delegate to ccw-exec for unified handling
|
||||
try {
|
||||
// Read and parse status.json
|
||||
if (!existsSync(filePath)) {
|
||||
return { success: false, message: 'Status file not found' };
|
||||
const result = await executeCliCommand('ccw', ['hook', 'parse-status', filePath]);
|
||||
|
||||
if (result.success) {
|
||||
return {
|
||||
success: true,
|
||||
message: result.output,
|
||||
_deprecated: true,
|
||||
_migration: 'Use /api/hook/ccw-exec with command=parse-status'
|
||||
};
|
||||
} else {
|
||||
return {
|
||||
success: false,
|
||||
error: result.error,
|
||||
_deprecated: true
|
||||
};
|
||||
}
|
||||
|
||||
const statusContent = readFileSync(filePath, 'utf8');
|
||||
const status = JSON.parse(statusContent);
|
||||
|
||||
// Extract key information
|
||||
const sessionId = status.session_id || 'unknown';
|
||||
const workflow = status.workflow || status.mode || 'unknown';
|
||||
|
||||
// Find current command (running or last completed)
|
||||
let currentCommand = status.command_chain?.find((cmd: { status: string }) => cmd.status === 'running')?.command;
|
||||
if (!currentCommand) {
|
||||
const completed = status.command_chain?.filter((cmd: { status: string }) => cmd.status === 'completed');
|
||||
currentCommand = completed?.[completed.length - 1]?.command || 'unknown';
|
||||
}
|
||||
|
||||
// Find next command (first pending)
|
||||
const nextCommand = status.command_chain?.find((cmd: { status: string }) => cmd.status === 'pending')?.command || '无';
|
||||
|
||||
// Format status message
|
||||
const message = `📋 CCW Status [${sessionId}] (${workflow}): 当前处于 ${currentCommand}，下一个命令 ${nextCommand}`;
|
||||
|
||||
return {
|
||||
success: true,
|
||||
message,
|
||||
sessionId,
|
||||
workflow,
|
||||
currentCommand,
|
||||
nextCommand
|
||||
};
|
||||
} catch (error) {
|
||||
console.error('[Hooks] Failed to parse CCW status:', error);
|
||||
return {
|
||||
success: false,
|
||||
error: (error as Error).message
|
||||
error: (error as Error).message,
|
||||
_deprecated: true
|
||||
};
|
||||
}
|
||||
});
|
||||
|
||||
565
ccw/src/core/services/checkpoint-service.ts
Normal file
565
ccw/src/core/services/checkpoint-service.ts
Normal file
@@ -0,0 +1,565 @@
|
||||
/**
|
||||
* CheckpointService - Session Checkpoint Management
|
||||
*
|
||||
* Creates and manages session checkpoints for state preservation during
|
||||
* context compaction and workflow transitions.
|
||||
*
|
||||
* Features:
|
||||
* - Checkpoint creation with workflow and mode state
|
||||
* - Checkpoint storage in .workflow/checkpoints/
|
||||
* - Automatic cleanup of old checkpoints (keeps last 10)
|
||||
* - Recovery message formatting for context injection
|
||||
*
|
||||
* Based on oh-my-claudecode pre-compact pattern.
|
||||
*/
|
||||
|
||||
import {
|
||||
existsSync,
|
||||
readFileSync,
|
||||
writeFileSync,
|
||||
mkdirSync,
|
||||
readdirSync,
|
||||
statSync,
|
||||
unlinkSync
|
||||
} from 'fs';
|
||||
import { join, basename } from 'path';
|
||||
import { ExecutionMode, MODE_CONFIGS } from './mode-registry-service.js';
|
||||
|
||||
// =============================================================================
|
||||
// Types
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Checkpoint trigger type
|
||||
*/
|
||||
export type CheckpointTrigger = 'manual' | 'auto' | 'compact' | 'mode-switch' | 'session-end';
|
||||
|
||||
/**
|
||||
* Workflow state snapshot
|
||||
*/
|
||||
export interface WorkflowStateSnapshot {
|
||||
/** Workflow type identifier */
|
||||
type: string;
|
||||
/** Current phase of the workflow */
|
||||
phase: string;
|
||||
/** Task IDs in pending state */
|
||||
pending: string[];
|
||||
/** Task IDs in completed state */
|
||||
completed: string[];
|
||||
/** Additional workflow metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mode state snapshot for a single mode
|
||||
*/
|
||||
export interface ModeStateSnapshot {
|
||||
/** Whether the mode is active */
|
||||
active: boolean;
|
||||
/** Mode-specific phase or stage */
|
||||
phase?: string;
|
||||
/** ISO timestamp when mode was activated */
|
||||
activatedAt?: string;
|
||||
/** Additional mode-specific data */
|
||||
data?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Memory context snapshot
|
||||
*/
|
||||
export interface MemoryContextSnapshot {
|
||||
/** Brief summary of accumulated context */
|
||||
summary: string;
|
||||
/** Key entities identified in the session */
|
||||
keyEntities: string[];
|
||||
/** Important decisions made */
|
||||
decisions?: string[];
|
||||
/** Open questions or blockers */
|
||||
openQuestions?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Full checkpoint data structure
|
||||
*/
|
||||
export interface Checkpoint {
|
||||
/** Unique checkpoint ID (timestamp-sessionId) */
|
||||
id: string;
|
||||
/** ISO timestamp of checkpoint creation */
|
||||
created_at: string;
|
||||
/** What triggered the checkpoint */
|
||||
trigger: CheckpointTrigger;
|
||||
/** Session ID this checkpoint belongs to */
|
||||
session_id: string;
|
||||
/** Project path */
|
||||
project_path: string;
|
||||
/** Workflow state snapshot */
|
||||
workflow_state: WorkflowStateSnapshot | null;
|
||||
/** Active mode states */
|
||||
mode_states: Partial<Record<ExecutionMode, ModeStateSnapshot>>;
|
||||
/** Memory context summary */
|
||||
memory_context: MemoryContextSnapshot | null;
|
||||
/** TODO summary if available */
|
||||
todo_summary?: {
|
||||
pending: number;
|
||||
in_progress: number;
|
||||
completed: number;
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Checkpoint metadata for listing
|
||||
*/
|
||||
export interface CheckpointMeta {
|
||||
/** Checkpoint ID */
|
||||
id: string;
|
||||
/** Creation timestamp */
|
||||
created_at: string;
|
||||
/** Session ID */
|
||||
session_id: string;
|
||||
/** Trigger type */
|
||||
trigger: CheckpointTrigger;
|
||||
/** File path */
|
||||
path: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Options for checkpoint service
|
||||
*/
|
||||
export interface CheckpointServiceOptions {
|
||||
/** Project root path */
|
||||
projectPath: string;
|
||||
/** Maximum checkpoints to keep per session (default: 10) */
|
||||
maxCheckpointsPerSession?: number;
|
||||
/** Enable logging */
|
||||
enableLogging?: boolean;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Constants
|
||||
// =============================================================================
|
||||
|
||||
/** Default maximum checkpoints to keep per session */
|
||||
const DEFAULT_MAX_CHECKPOINTS = 10;
|
||||
|
||||
/** Checkpoint directory name within .workflow */
|
||||
const CHECKPOINT_DIR_NAME = 'checkpoints';
|
||||
|
||||
// =============================================================================
|
||||
// CheckpointService Class
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Service for managing session checkpoints
|
||||
*/
|
||||
export class CheckpointService {
|
||||
private projectPath: string;
|
||||
private checkpointsDir: string;
|
||||
private maxCheckpoints: number;
|
||||
private enableLogging: boolean;
|
||||
|
||||
constructor(options: CheckpointServiceOptions) {
|
||||
this.projectPath = options.projectPath;
|
||||
this.checkpointsDir = join(this.projectPath, '.workflow', CHECKPOINT_DIR_NAME);
|
||||
this.maxCheckpoints = options.maxCheckpointsPerSession ?? DEFAULT_MAX_CHECKPOINTS;
|
||||
this.enableLogging = options.enableLogging ?? false;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Checkpoint Creation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Create a checkpoint for a session
|
||||
*
|
||||
* @param sessionId - The session ID
|
||||
* @param trigger - What triggered the checkpoint
|
||||
* @param options - Optional additional data
|
||||
* @returns Promise resolving to the created checkpoint
|
||||
*/
|
||||
async createCheckpoint(
|
||||
sessionId: string,
|
||||
trigger: CheckpointTrigger,
|
||||
options?: {
|
||||
workflowState?: WorkflowStateSnapshot | null;
|
||||
modeStates?: Partial<Record<ExecutionMode, ModeStateSnapshot>>;
|
||||
memoryContext?: MemoryContextSnapshot | null;
|
||||
todoSummary?: { pending: number; in_progress: number; completed: number };
|
||||
}
|
||||
): Promise<Checkpoint> {
|
||||
const timestamp = new Date().toISOString();
|
||||
const checkpointId = this.generateCheckpointId(sessionId, timestamp);
|
||||
|
||||
const checkpoint: Checkpoint = {
|
||||
id: checkpointId,
|
||||
created_at: timestamp,
|
||||
trigger,
|
||||
session_id: sessionId,
|
||||
project_path: this.projectPath,
|
||||
workflow_state: options?.workflowState ?? null,
|
||||
mode_states: options?.modeStates ?? {},
|
||||
memory_context: options?.memoryContext ?? null,
|
||||
todo_summary: options?.todoSummary
|
||||
};
|
||||
|
||||
this.log(`Created checkpoint ${checkpointId} for session ${sessionId} (trigger: ${trigger})`);
|
||||
return checkpoint;
|
||||
}
|
||||
|
||||
/**
|
||||
* Save a checkpoint to disk
|
||||
*
|
||||
* @param checkpoint - The checkpoint to save
|
||||
* @returns The checkpoint ID
|
||||
*/
|
||||
async saveCheckpoint(checkpoint: Checkpoint): Promise<string> {
|
||||
this.ensureCheckpointsDir();
|
||||
|
||||
const filename = `${checkpoint.id}.json`;
|
||||
const filepath = join(this.checkpointsDir, filename);
|
||||
|
||||
try {
|
||||
writeFileSync(filepath, JSON.stringify(checkpoint, null, 2), 'utf-8');
|
||||
this.log(`Saved checkpoint to ${filepath}`);
|
||||
|
||||
// Clean up old checkpoints for this session
|
||||
await this.cleanupOldCheckpoints(checkpoint.session_id);
|
||||
|
||||
return checkpoint.id;
|
||||
} catch (error) {
|
||||
this.log(`Error saving checkpoint: ${(error as Error).message}`);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Load a checkpoint from disk
|
||||
*
|
||||
* @param checkpointId - The checkpoint ID to load
|
||||
* @returns The checkpoint or null if not found
|
||||
*/
|
||||
async loadCheckpoint(checkpointId: string): Promise<Checkpoint | null> {
|
||||
const filepath = join(this.checkpointsDir, `${checkpointId}.json`);
|
||||
|
||||
if (!existsSync(filepath)) {
|
||||
this.log(`Checkpoint not found: ${checkpointId}`);
|
||||
return null;
|
||||
}
|
||||
|
||||
try {
|
||||
const content = readFileSync(filepath, 'utf-8');
|
||||
const checkpoint = JSON.parse(content) as Checkpoint;
|
||||
this.log(`Loaded checkpoint ${checkpointId}`);
|
||||
return checkpoint;
|
||||
} catch (error) {
|
||||
this.log(`Error loading checkpoint ${checkpointId}: ${(error as Error).message}`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Checkpoint Listing
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* List all checkpoints, optionally filtered by session
|
||||
*
|
||||
* @param sessionId - Optional session ID to filter by
|
||||
* @returns Array of checkpoint metadata
|
||||
*/
|
||||
async listCheckpoints(sessionId?: string): Promise<CheckpointMeta[]> {
|
||||
if (!existsSync(this.checkpointsDir)) {
|
||||
return [];
|
||||
}
|
||||
|
||||
try {
|
||||
const files = readdirSync(this.checkpointsDir)
|
||||
.filter(f => f.endsWith('.json'))
|
||||
.map(f => join(this.checkpointsDir, f));
|
||||
|
||||
const checkpoints: CheckpointMeta[] = [];
|
||||
|
||||
for (const filepath of files) {
|
||||
try {
|
||||
const content = readFileSync(filepath, 'utf-8');
|
||||
const checkpoint = JSON.parse(content) as Checkpoint;
|
||||
|
||||
// Filter by session if provided
|
||||
if (sessionId && checkpoint.session_id !== sessionId) {
|
||||
continue;
|
||||
}
|
||||
|
||||
checkpoints.push({
|
||||
id: checkpoint.id,
|
||||
created_at: checkpoint.created_at,
|
||||
session_id: checkpoint.session_id,
|
||||
trigger: checkpoint.trigger,
|
||||
path: filepath
|
||||
});
|
||||
} catch {
|
||||
// Skip invalid checkpoint files
|
||||
}
|
||||
}
|
||||
|
||||
// Sort by creation time (newest first)
|
||||
checkpoints.sort((a, b) =>
|
||||
new Date(b.created_at).getTime() - new Date(a.created_at).getTime()
|
||||
);
|
||||
|
||||
return checkpoints;
|
||||
} catch (error) {
|
||||
this.log(`Error listing checkpoints: ${(error as Error).message}`);
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the most recent checkpoint for a session
|
||||
*
|
||||
* @param sessionId - The session ID
|
||||
* @returns The most recent checkpoint or null
|
||||
*/
|
||||
async getLatestCheckpoint(sessionId: string): Promise<Checkpoint | null> {
|
||||
const checkpoints = await this.listCheckpoints(sessionId);
|
||||
if (checkpoints.length === 0) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return this.loadCheckpoint(checkpoints[0].id);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Recovery Message Formatting
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Format a checkpoint as a recovery message for context injection
|
||||
*
|
||||
* @param checkpoint - The checkpoint to format
|
||||
* @returns Formatted markdown string
|
||||
*/
|
||||
formatRecoveryMessage(checkpoint: Checkpoint): string {
|
||||
const lines: string[] = [
|
||||
'# Session Checkpoint Recovery',
|
||||
'',
|
||||
`**Checkpoint ID:** ${checkpoint.id}`,
|
||||
`**Created:** ${checkpoint.created_at}`,
|
||||
`**Trigger:** ${checkpoint.trigger}`,
|
||||
`**Session:** ${checkpoint.session_id}`,
|
||||
''
|
||||
];
|
||||
|
||||
// Workflow state section
|
||||
if (checkpoint.workflow_state) {
|
||||
const ws = checkpoint.workflow_state;
|
||||
lines.push('## Workflow State');
|
||||
lines.push('');
|
||||
lines.push(`- **Type:** ${ws.type}`);
|
||||
lines.push(`- **Phase:** ${ws.phase}`);
|
||||
if (ws.pending.length > 0) {
|
||||
lines.push(`- **Pending Tasks:** ${ws.pending.length}`);
|
||||
}
|
||||
if (ws.completed.length > 0) {
|
||||
lines.push(`- **Completed Tasks:** ${ws.completed.length}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
// Active modes section
|
||||
const activeModes = Object.entries(checkpoint.mode_states)
|
||||
.filter(([, state]) => state.active);
|
||||
|
||||
if (activeModes.length > 0) {
|
||||
lines.push('## Active Modes');
|
||||
lines.push('');
|
||||
|
||||
for (const [mode, state] of activeModes) {
|
||||
const modeConfig = MODE_CONFIGS[mode as ExecutionMode];
|
||||
const modeName = modeConfig?.name ?? mode;
|
||||
lines.push(`- **${modeName}**`);
|
||||
if (state.phase) {
|
||||
lines.push(` - Phase: ${state.phase}`);
|
||||
}
|
||||
if (state.activatedAt) {
|
||||
const age = Math.round(
|
||||
(Date.now() - new Date(state.activatedAt).getTime()) / 60000
|
||||
);
|
||||
lines.push(` - Active for: ${age} minutes`);
|
||||
}
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
// TODO summary section
|
||||
if (checkpoint.todo_summary) {
|
||||
const todo = checkpoint.todo_summary;
|
||||
const total = todo.pending + todo.in_progress + todo.completed;
|
||||
|
||||
if (total > 0) {
|
||||
lines.push('## TODO Summary');
|
||||
lines.push('');
|
||||
lines.push(`- Pending: ${todo.pending}`);
|
||||
lines.push(`- In Progress: ${todo.in_progress}`);
|
||||
lines.push(`- Completed: ${todo.completed}`);
|
||||
lines.push('');
|
||||
}
|
||||
}
|
||||
|
||||
// Memory context section
|
||||
if (checkpoint.memory_context) {
|
||||
const mem = checkpoint.memory_context;
|
||||
lines.push('## Context Memory');
|
||||
lines.push('');
|
||||
|
||||
if (mem.summary) {
|
||||
lines.push(mem.summary);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (mem.keyEntities.length > 0) {
|
||||
lines.push(`**Key Entities:** ${mem.keyEntities.join(', ')}`);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (mem.decisions && mem.decisions.length > 0) {
|
||||
lines.push('**Decisions Made:**');
|
||||
for (const decision of mem.decisions) {
|
||||
lines.push(`- ${decision}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (mem.openQuestions && mem.openQuestions.length > 0) {
|
||||
lines.push('**Open Questions:**');
|
||||
for (const question of mem.openQuestions) {
|
||||
lines.push(`- ${question}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
}
|
||||
|
||||
// Recovery instructions
|
||||
lines.push('---');
|
||||
lines.push('');
|
||||
lines.push('*This checkpoint was created to preserve session state.*');
|
||||
lines.push('*Review the information above to resume work effectively.*');
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Cleanup
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Delete a specific checkpoint
|
||||
*
|
||||
* @param checkpointId - The checkpoint ID to delete
|
||||
* @returns true if deleted successfully
|
||||
*/
|
||||
async deleteCheckpoint(checkpointId: string): Promise<boolean> {
|
||||
const filepath = join(this.checkpointsDir, `${checkpointId}.json`);
|
||||
|
||||
if (!existsSync(filepath)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
try {
|
||||
unlinkSync(filepath);
|
||||
this.log(`Deleted checkpoint ${checkpointId}`);
|
||||
return true;
|
||||
} catch (error) {
|
||||
this.log(`Error deleting checkpoint ${checkpointId}: ${(error as Error).message}`);
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Clean up old checkpoints for a session, keeping only the most recent
|
||||
*
|
||||
* @param sessionId - The session ID
|
||||
* @returns Number of checkpoints removed
|
||||
*/
|
||||
async cleanupOldCheckpoints(sessionId: string): Promise<number> {
|
||||
const checkpoints = await this.listCheckpoints(sessionId);
|
||||
|
||||
if (checkpoints.length <= this.maxCheckpoints) {
|
||||
return 0;
|
||||
}
|
||||
|
||||
// Remove oldest checkpoints (those beyond the limit)
|
||||
const toRemove = checkpoints.slice(this.maxCheckpoints);
|
||||
let removed = 0;
|
||||
|
||||
for (const meta of toRemove) {
|
||||
if (await this.deleteCheckpoint(meta.id)) {
|
||||
removed++;
|
||||
}
|
||||
}
|
||||
|
||||
this.log(`Cleaned up ${removed} old checkpoints for session ${sessionId}`);
|
||||
return removed;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Utility
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Get the checkpoints directory path
|
||||
*/
|
||||
getCheckpointsDir(): string {
|
||||
return this.checkpointsDir;
|
||||
}
|
||||
|
||||
/**
|
||||
* Ensure the checkpoints directory exists
|
||||
*/
|
||||
ensureCheckpointsDir(): void {
|
||||
if (!existsSync(this.checkpointsDir)) {
|
||||
mkdirSync(this.checkpointsDir, { recursive: true });
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Private: Helper Methods
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Generate a unique checkpoint ID
|
||||
*/
|
||||
private generateCheckpointId(sessionId: string, timestamp: string): string {
|
||||
// Format: YYYY-MM-DDTHH-mm-ss-sessionId
|
||||
const safeTimestamp = timestamp.replace(/[:.]/g, '-').substring(0, 19);
|
||||
return `${safeTimestamp}-${sessionId.substring(0, 8)}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Log a message if logging is enabled
|
||||
*/
|
||||
private log(message: string): void {
|
||||
if (this.enableLogging) {
|
||||
console.log(`[CheckpointService] ${message}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Factory Function
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Create a CheckpointService instance
|
||||
*
|
||||
* @param projectPath - Project root path
|
||||
* @param options - Optional configuration
|
||||
* @returns CheckpointService instance
|
||||
*/
|
||||
export function createCheckpointService(
|
||||
projectPath: string,
|
||||
options?: Partial<CheckpointServiceOptions>
|
||||
): CheckpointService {
|
||||
return new CheckpointService({
|
||||
projectPath,
|
||||
...options
|
||||
});
|
||||
}
|
||||
336
ccw/src/core/services/hook-context-service.ts
Normal file
336
ccw/src/core/services/hook-context-service.ts
Normal file
@@ -0,0 +1,336 @@
|
||||
/**
|
||||
* HookContextService - Unified context generation for Claude Code hooks
|
||||
*
|
||||
* Provides centralized context generation for:
|
||||
* - session-start: MEMORY.md summary + cluster overview + hot entities + patterns
|
||||
* - per-prompt: vector search + intent matching
|
||||
* - session-end: task generation for async background processing
|
||||
*
|
||||
* Character limits:
|
||||
* - session-start: <= 1000 chars
|
||||
* - per-prompt: <= 500 chars
|
||||
*/
|
||||
|
||||
import type { SessionEndTask } from '../unified-context-builder.js';
|
||||
import { SessionStateService, type SessionState } from './session-state-service.js';
|
||||
|
||||
// =============================================================================
|
||||
// Constants
|
||||
// =============================================================================
|
||||
|
||||
/** Maximum character count for session-start context */
|
||||
const SESSION_START_LIMIT = 1000;
|
||||
|
||||
/** Maximum character count for per-prompt context */
|
||||
const PER_PROMPT_LIMIT = 500;
|
||||
|
||||
// =============================================================================
|
||||
// Types
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Options for building context
|
||||
*/
|
||||
export interface BuildContextOptions {
|
||||
/** Session ID for state tracking */
|
||||
sessionId: string;
|
||||
/** Project root path */
|
||||
projectId?: string;
|
||||
/** Whether this is the first prompt in the session */
|
||||
isFirstPrompt?: boolean;
|
||||
/** Character limit for the generated context */
|
||||
charLimit?: number;
|
||||
/** Current prompt text (for per-prompt context) */
|
||||
prompt?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Context generation result
|
||||
*/
|
||||
export interface ContextResult {
|
||||
/** Generated context content */
|
||||
content: string;
|
||||
/** Type of context generated */
|
||||
type: 'session-start' | 'context';
|
||||
/** Whether this was the first prompt */
|
||||
isFirstPrompt: boolean;
|
||||
/** Updated session state */
|
||||
state: SessionState;
|
||||
/** Character count of generated content */
|
||||
charCount: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Options for HookContextService
|
||||
*/
|
||||
export interface HookContextServiceOptions {
|
||||
/** Project root path */
|
||||
projectPath: string;
|
||||
/** Storage type for session state */
|
||||
storageType?: 'global' | 'session-scoped';
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// HookContextService
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Service for generating hook context
|
||||
*
|
||||
* This service wraps UnifiedContextBuilder and SessionStateService to provide
|
||||
* a unified interface for context generation across CLI hooks and API routes.
|
||||
*/
|
||||
export class HookContextService {
|
||||
private projectPath: string;
|
||||
private sessionStateService: SessionStateService;
|
||||
private unifiedContextBuilder: InstanceType<typeof import('../unified-context-builder.js').UnifiedContextBuilder> | null = null;
|
||||
private clusteringService: InstanceType<typeof import('../session-clustering-service.js').SessionClusteringService> | null = null;
|
||||
private initialized = false;
|
||||
|
||||
constructor(options: HookContextServiceOptions) {
|
||||
this.projectPath = options.projectPath;
|
||||
this.sessionStateService = new SessionStateService({
|
||||
storageType: options.storageType,
|
||||
projectPath: options.projectPath
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Initialize lazy-loaded services
|
||||
*/
|
||||
private async initialize(): Promise<void> {
|
||||
if (this.initialized) return;
|
||||
|
||||
try {
|
||||
// Try to load UnifiedContextBuilder (requires embedder)
|
||||
const { isUnifiedEmbedderAvailable } = await import('../unified-vector-index.js');
|
||||
if (isUnifiedEmbedderAvailable()) {
|
||||
const { UnifiedContextBuilder } = await import('../unified-context-builder.js');
|
||||
this.unifiedContextBuilder = new UnifiedContextBuilder(this.projectPath);
|
||||
}
|
||||
} catch {
|
||||
// UnifiedContextBuilder not available
|
||||
}
|
||||
|
||||
try {
|
||||
// Always load SessionClusteringService as fallback
|
||||
const { SessionClusteringService } = await import('../session-clustering-service.js');
|
||||
this.clusteringService = new SessionClusteringService(this.projectPath);
|
||||
} catch {
|
||||
// SessionClusteringService not available
|
||||
}
|
||||
|
||||
this.initialized = true;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Context Generation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Build context for session-start hook
|
||||
*
|
||||
* @param options - Build context options
|
||||
* @returns Context generation result
|
||||
*/
|
||||
async buildSessionStartContext(options: BuildContextOptions): Promise<ContextResult> {
|
||||
await this.initialize();
|
||||
|
||||
const charLimit = options.charLimit ?? SESSION_START_LIMIT;
|
||||
|
||||
// Update session state
|
||||
const { isFirstPrompt, state } = this.sessionStateService.incrementLoad(
|
||||
options.sessionId,
|
||||
options.prompt
|
||||
);
|
||||
|
||||
let content = '';
|
||||
|
||||
// Try UnifiedContextBuilder first
|
||||
if (this.unifiedContextBuilder) {
|
||||
content = await this.unifiedContextBuilder.buildSessionStartContext();
|
||||
} else if (this.clusteringService) {
|
||||
// Fallback to SessionClusteringService
|
||||
content = await this.clusteringService.getProgressiveIndex({
|
||||
type: 'session-start',
|
||||
sessionId: options.sessionId
|
||||
});
|
||||
}
|
||||
|
||||
// Truncate if needed
|
||||
if (content.length > charLimit) {
|
||||
content = content.substring(0, charLimit - 20) + '...';
|
||||
}
|
||||
|
||||
return {
|
||||
content,
|
||||
type: 'session-start',
|
||||
isFirstPrompt,
|
||||
state,
|
||||
charCount: content.length
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Build context for per-prompt hook
|
||||
*
|
||||
* @param options - Build context options
|
||||
* @returns Context generation result
|
||||
*/
|
||||
async buildPromptContext(options: BuildContextOptions): Promise<ContextResult> {
|
||||
await this.initialize();
|
||||
|
||||
const charLimit = options.charLimit ?? PER_PROMPT_LIMIT;
|
||||
|
||||
// Update session state
|
||||
const { isFirstPrompt, state } = this.sessionStateService.incrementLoad(
|
||||
options.sessionId,
|
||||
options.prompt
|
||||
);
|
||||
|
||||
let content = '';
|
||||
let contextType: 'session-start' | 'context' = 'context';
|
||||
|
||||
// First prompt uses session-start context
|
||||
if (isFirstPrompt) {
|
||||
contextType = 'session-start';
|
||||
if (this.unifiedContextBuilder) {
|
||||
content = await this.unifiedContextBuilder.buildSessionStartContext();
|
||||
} else if (this.clusteringService) {
|
||||
content = await this.clusteringService.getProgressiveIndex({
|
||||
type: 'session-start',
|
||||
sessionId: options.sessionId
|
||||
});
|
||||
}
|
||||
} else if (options.prompt && options.prompt.trim().length > 0) {
|
||||
// Subsequent prompts use per-prompt context
|
||||
contextType = 'context';
|
||||
if (this.unifiedContextBuilder) {
|
||||
content = await this.unifiedContextBuilder.buildPromptContext(options.prompt);
|
||||
} else if (this.clusteringService) {
|
||||
content = await this.clusteringService.getProgressiveIndex({
|
||||
type: 'context',
|
||||
sessionId: options.sessionId,
|
||||
prompt: options.prompt
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Truncate if needed
|
||||
if (content.length > charLimit) {
|
||||
content = content.substring(0, charLimit - 20) + '...';
|
||||
}
|
||||
|
||||
return {
|
||||
content,
|
||||
type: contextType,
|
||||
isFirstPrompt,
|
||||
state,
|
||||
charCount: content.length
|
||||
};
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Session End Tasks
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Build session end tasks for async background processing
|
||||
*
|
||||
* @param sessionId - Session ID for context
|
||||
* @returns Array of tasks to execute
|
||||
*/
|
||||
async buildSessionEndTasks(sessionId: string): Promise<SessionEndTask[]> {
|
||||
await this.initialize();
|
||||
|
||||
if (this.unifiedContextBuilder) {
|
||||
return this.unifiedContextBuilder.buildSessionEndTasks(sessionId);
|
||||
}
|
||||
|
||||
// No tasks available without UnifiedContextBuilder
|
||||
return [];
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Session State Management
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Get session state
|
||||
*
|
||||
* @param sessionId - Session ID
|
||||
* @returns Session state or null if not found
|
||||
*/
|
||||
getSessionState(sessionId: string): SessionState | null {
|
||||
return this.sessionStateService.load(sessionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if this is the first prompt for a session
|
||||
*
|
||||
* @param sessionId - Session ID
|
||||
* @returns true if this is the first prompt
|
||||
*/
|
||||
isFirstPrompt(sessionId: string): boolean {
|
||||
return this.sessionStateService.isFirstLoad(sessionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get load count for a session
|
||||
*
|
||||
* @param sessionId - Session ID
|
||||
* @returns Load count (0 if not found)
|
||||
*/
|
||||
getLoadCount(sessionId: string): number {
|
||||
return this.sessionStateService.getLoadCount(sessionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear session state
|
||||
*
|
||||
* @param sessionId - Session ID
|
||||
* @returns true if state was cleared
|
||||
*/
|
||||
clearSessionState(sessionId: string): boolean {
|
||||
return this.sessionStateService.clear(sessionId);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Utility Methods
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Check if UnifiedContextBuilder is available
|
||||
*
|
||||
* @returns true if embedder is available
|
||||
*/
|
||||
async isAdvancedContextAvailable(): Promise<boolean> {
|
||||
await this.initialize();
|
||||
return this.unifiedContextBuilder !== null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the project path
|
||||
*/
|
||||
getProjectPath(): string {
|
||||
return this.projectPath;
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Factory Function
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Create a HookContextService instance
|
||||
*
|
||||
* @param projectPath - Project root path
|
||||
* @param storageType - Storage type for session state
|
||||
* @returns HookContextService instance
|
||||
*/
|
||||
export function createHookContextService(
|
||||
projectPath: string,
|
||||
storageType?: 'global' | 'session-scoped'
|
||||
): HookContextService {
|
||||
return new HookContextService({ projectPath, storageType });
|
||||
}
|
||||
75
ccw/src/core/services/index.ts
Normal file
75
ccw/src/core/services/index.ts
Normal file
@@ -0,0 +1,75 @@
|
||||
/**
|
||||
* Core Services Exports
|
||||
*
|
||||
* Central export point for all CCW core services.
|
||||
*/
|
||||
|
||||
// Session State Management
|
||||
export {
|
||||
SessionStateService,
|
||||
loadSessionState,
|
||||
saveSessionState,
|
||||
clearSessionState,
|
||||
updateSessionState,
|
||||
incrementSessionLoad,
|
||||
getSessionStatePath,
|
||||
validateSessionId
|
||||
} from './session-state-service.js';
|
||||
export type {
|
||||
SessionState,
|
||||
SessionStateOptions,
|
||||
SessionStorageType
|
||||
} from './session-state-service.js';
|
||||
|
||||
// Hook Context Service
|
||||
export { HookContextService } from './hook-context-service.js';
|
||||
export type { BuildContextOptions, ContextResult } from './hook-context-service.js';
|
||||
|
||||
// Session End Service
|
||||
export { SessionEndService } from './session-end-service.js';
|
||||
export type { EndTask, TaskResult } from './session-end-service.js';
|
||||
|
||||
// Mode Registry Service
|
||||
export {
|
||||
ModeRegistryService,
|
||||
MODE_CONFIGS,
|
||||
EXCLUSIVE_MODES,
|
||||
STALE_MARKER_THRESHOLD,
|
||||
createModeRegistryService
|
||||
} from './mode-registry-service.js';
|
||||
export type {
|
||||
ModeConfig,
|
||||
ModeStatus,
|
||||
ModeRegistryOptions,
|
||||
CanStartResult,
|
||||
ExecutionMode
|
||||
} from './mode-registry-service.js';
|
||||
|
||||
// Checkpoint Service
|
||||
export { CheckpointService, createCheckpointService } from './checkpoint-service.js';
|
||||
export type {
|
||||
CheckpointServiceOptions,
|
||||
Checkpoint,
|
||||
CheckpointMeta,
|
||||
CheckpointTrigger,
|
||||
WorkflowStateSnapshot,
|
||||
ModeStateSnapshot,
|
||||
MemoryContextSnapshot
|
||||
} from './checkpoint-service.js';
|
||||
|
||||
// CLI Session Manager
|
||||
export { CliSessionManager } from './cli-session-manager.js';
|
||||
export type {
|
||||
CliSession,
|
||||
CreateCliSessionOptions,
|
||||
ExecuteInCliSessionOptions,
|
||||
CliSessionOutputEvent
|
||||
} from './cli-session-manager.js';
|
||||
|
||||
// Flow Executor
|
||||
export { FlowExecutor } from './flow-executor.js';
|
||||
export type { ExecutionContext, NodeResult } from './flow-executor.js';
|
||||
|
||||
// CLI Launch Registry
|
||||
export { getLaunchConfig } from './cli-launch-registry.js';
|
||||
export type { CliLaunchConfig, CliTool, LaunchMode } from './cli-launch-registry.js';
|
||||
730
ccw/src/core/services/mode-registry-service.ts
Normal file
730
ccw/src/core/services/mode-registry-service.ts
Normal file
@@ -0,0 +1,730 @@
|
||||
/**
|
||||
* ModeRegistryService - Centralized Mode State Management
|
||||
*
|
||||
* Provides unified mode state detection and management for CCW.
|
||||
* All modes store state in `.workflow/modes/` directory for consistency.
|
||||
*
|
||||
* Features:
|
||||
* - Mode activation/deactivation tracking
|
||||
* - Exclusive mode conflict detection
|
||||
* - Stale marker cleanup (1 hour threshold)
|
||||
* - File-based state persistence
|
||||
*
|
||||
* Based on oh-my-claudecode mode-registry pattern.
|
||||
*/
|
||||
|
||||
import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, readdirSync, statSync, rmSync } from 'fs';
|
||||
import { join, dirname } from 'path';
|
||||
|
||||
// =============================================================================
|
||||
// Types
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Supported execution modes
|
||||
*/
|
||||
export type ExecutionMode =
|
||||
| 'autopilot'
|
||||
| 'ralph'
|
||||
| 'ultrawork'
|
||||
| 'swarm'
|
||||
| 'pipeline'
|
||||
| 'team'
|
||||
| 'ultraqa';
|
||||
|
||||
/**
|
||||
* Mode configuration
|
||||
*/
|
||||
export interface ModeConfig {
|
||||
/** Display name for the mode */
|
||||
name: string;
|
||||
/** Primary state file path (relative to .workflow/modes/) */
|
||||
stateFile: string;
|
||||
/** Property to check in JSON state for active status */
|
||||
activeProperty: string;
|
||||
/** Whether this mode is mutually exclusive with other exclusive modes */
|
||||
exclusive?: boolean;
|
||||
/** Description of the mode */
|
||||
description?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Status of a mode
|
||||
*/
|
||||
export interface ModeStatus {
|
||||
/** The mode identifier */
|
||||
mode: ExecutionMode;
|
||||
/** Whether the mode is currently active */
|
||||
active: boolean;
|
||||
/** Path to the state file */
|
||||
stateFilePath: string;
|
||||
/** Session ID if session-scoped */
|
||||
sessionId?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Result of checking if a mode can be started
|
||||
*/
|
||||
export interface CanStartResult {
|
||||
/** Whether the mode can be started */
|
||||
allowed: boolean;
|
||||
/** The mode that is blocking (if not allowed) */
|
||||
blockedBy?: ExecutionMode;
|
||||
/** Human-readable message */
|
||||
message?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Options for mode registry operations
|
||||
*/
|
||||
export interface ModeRegistryOptions {
|
||||
/** Project root path */
|
||||
projectPath: string;
|
||||
/** Enable logging */
|
||||
enableLogging?: boolean;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Constants
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Stale marker threshold (1 hour)
|
||||
* Markers older than this are auto-removed to prevent crashed sessions
|
||||
* from blocking indefinitely.
|
||||
*/
|
||||
const STALE_MARKER_THRESHOLD = 60 * 60 * 1000; // 1 hour in milliseconds
|
||||
|
||||
/**
|
||||
* Mode configuration registry
|
||||
*
|
||||
* Maps each mode to its state file location and detection method.
|
||||
* All paths are relative to .workflow/modes/ directory.
|
||||
*/
|
||||
const MODE_CONFIGS: Record<ExecutionMode, ModeConfig> = {
|
||||
autopilot: {
|
||||
name: 'Autopilot',
|
||||
stateFile: 'autopilot-state.json',
|
||||
activeProperty: 'active',
|
||||
exclusive: true,
|
||||
description: 'Autonomous execution mode for multi-step tasks'
|
||||
},
|
||||
ralph: {
|
||||
name: 'Ralph',
|
||||
stateFile: 'ralph-state.json',
|
||||
activeProperty: 'active',
|
||||
exclusive: false,
|
||||
description: 'Research and Analysis Learning Pattern Handler'
|
||||
},
|
||||
ultrawork: {
|
||||
name: 'Ultrawork',
|
||||
stateFile: 'ultrawork-state.json',
|
||||
activeProperty: 'active',
|
||||
exclusive: false,
|
||||
description: 'Ultra-focused work mode for deep tasks'
|
||||
},
|
||||
swarm: {
|
||||
name: 'Swarm',
|
||||
stateFile: 'swarm-state.json',
|
||||
activeProperty: 'active',
|
||||
exclusive: true,
|
||||
description: 'Multi-agent swarm execution mode'
|
||||
},
|
||||
pipeline: {
|
||||
name: 'Pipeline',
|
||||
stateFile: 'pipeline-state.json',
|
||||
activeProperty: 'active',
|
||||
exclusive: true,
|
||||
description: 'Pipeline execution mode for sequential tasks'
|
||||
},
|
||||
team: {
|
||||
name: 'Team',
|
||||
stateFile: 'team-state.json',
|
||||
activeProperty: 'active',
|
||||
exclusive: false,
|
||||
description: 'Team collaboration mode'
|
||||
},
|
||||
ultraqa: {
|
||||
name: 'UltraQA',
|
||||
stateFile: 'ultraqa-state.json',
|
||||
activeProperty: 'active',
|
||||
exclusive: false,
|
||||
description: 'Ultra-focused QA mode'
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Modes that are mutually exclusive (cannot run concurrently)
|
||||
*/
|
||||
const EXCLUSIVE_MODES: ExecutionMode[] = ['autopilot', 'swarm', 'pipeline'];
|
||||
|
||||
// Export for external use
|
||||
export { MODE_CONFIGS, EXCLUSIVE_MODES, STALE_MARKER_THRESHOLD };
|
||||
|
||||
// =============================================================================
|
||||
// ModeRegistryService
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Service for managing mode state
|
||||
*
|
||||
* This service provides centralized mode state management using file-based
|
||||
* persistence. It supports exclusive mode detection and stale marker cleanup.
|
||||
*/
|
||||
export class ModeRegistryService {
|
||||
private projectPath: string;
|
||||
private enableLogging: boolean;
|
||||
private modesDir: string;
|
||||
|
||||
constructor(options: ModeRegistryOptions) {
|
||||
this.projectPath = options.projectPath;
|
||||
this.enableLogging = options.enableLogging ?? false;
|
||||
this.modesDir = join(this.projectPath, '.workflow', 'modes');
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Directory Management
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Get the modes directory path
|
||||
*/
|
||||
getModesDir(): string {
|
||||
return this.modesDir;
|
||||
}
|
||||
|
||||
/**
|
||||
* Ensure the modes directory exists
|
||||
*/
|
||||
ensureModesDir(): void {
|
||||
if (!existsSync(this.modesDir)) {
|
||||
mkdirSync(this.modesDir, { recursive: true });
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Mode State Queries
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Check if a specific mode is currently active
|
||||
*
|
||||
* @param mode - The mode to check
|
||||
* @param sessionId - Optional session ID to check session-scoped state
|
||||
* @returns true if the mode is active
|
||||
*/
|
||||
isModeActive(mode: ExecutionMode, sessionId?: string): boolean {
|
||||
const config = MODE_CONFIGS[mode];
|
||||
|
||||
if (sessionId) {
|
||||
// Check session-scoped path
|
||||
const sessionStateFile = this.getSessionStatePath(mode, sessionId);
|
||||
return this.isJsonModeActive(sessionStateFile, config, sessionId);
|
||||
}
|
||||
|
||||
// Check legacy shared path
|
||||
const stateFile = this.getStateFilePath(mode);
|
||||
return this.isJsonModeActive(stateFile, config);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a mode has state (file exists)
|
||||
*
|
||||
* @param mode - The mode to check
|
||||
* @param sessionId - Optional session ID
|
||||
* @returns true if state file exists
|
||||
*/
|
||||
hasModeState(mode: ExecutionMode, sessionId?: string): boolean {
|
||||
const stateFile = sessionId
|
||||
? this.getSessionStatePath(mode, sessionId)
|
||||
: this.getStateFilePath(mode);
|
||||
return existsSync(stateFile);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all active modes
|
||||
*
|
||||
* @param sessionId - Optional session ID to check session-scoped state
|
||||
* @returns Array of active mode identifiers
|
||||
*/
|
||||
getActiveModes(sessionId?: string): ExecutionMode[] {
|
||||
const modes: ExecutionMode[] = [];
|
||||
|
||||
for (const mode of Object.keys(MODE_CONFIGS) as ExecutionMode[]) {
|
||||
if (this.isModeActive(mode, sessionId)) {
|
||||
modes.push(mode);
|
||||
}
|
||||
}
|
||||
|
||||
return modes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if any mode is currently active
|
||||
*
|
||||
* @param sessionId - Optional session ID
|
||||
* @returns true if any mode is active
|
||||
*/
|
||||
isAnyModeActive(sessionId?: string): boolean {
|
||||
return this.getActiveModes(sessionId).length > 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the currently active exclusive mode (if any)
|
||||
*
|
||||
* @returns The active exclusive mode or null
|
||||
*/
|
||||
getActiveExclusiveMode(): ExecutionMode | null {
|
||||
for (const mode of EXCLUSIVE_MODES) {
|
||||
if (this.isModeActiveInAnySession(mode)) {
|
||||
return mode;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get status of all modes
|
||||
*
|
||||
* @param sessionId - Optional session ID
|
||||
* @returns Array of mode statuses
|
||||
*/
|
||||
getAllModeStatuses(sessionId?: string): ModeStatus[] {
|
||||
return (Object.keys(MODE_CONFIGS) as ExecutionMode[]).map(mode => ({
|
||||
mode,
|
||||
active: this.isModeActive(mode, sessionId),
|
||||
stateFilePath: sessionId
|
||||
? this.getSessionStatePath(mode, sessionId)
|
||||
: this.getStateFilePath(mode),
|
||||
sessionId
|
||||
}));
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Mode Control
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Check if a new mode can be started
|
||||
*
|
||||
* @param mode - The mode to start
|
||||
* @param sessionId - Optional session ID
|
||||
* @returns CanStartResult with allowed status and blocker info
|
||||
*/
|
||||
canStartMode(mode: ExecutionMode, sessionId?: string): CanStartResult {
|
||||
const config = MODE_CONFIGS[mode];
|
||||
|
||||
// Check for mutually exclusive modes
|
||||
if (EXCLUSIVE_MODES.includes(mode)) {
|
||||
for (const exclusiveMode of EXCLUSIVE_MODES) {
|
||||
if (exclusiveMode !== mode && this.isModeActiveInAnySession(exclusiveMode)) {
|
||||
const exclusiveConfig = MODE_CONFIGS[exclusiveMode];
|
||||
return {
|
||||
allowed: false,
|
||||
blockedBy: exclusiveMode,
|
||||
message: `Cannot start ${config.name} while ${exclusiveConfig.name} is active. Cancel ${exclusiveConfig.name} first.`
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Check if already active in this session
|
||||
if (sessionId && this.isModeActive(mode, sessionId)) {
|
||||
return {
|
||||
allowed: false,
|
||||
blockedBy: mode,
|
||||
message: `${config.name} is already active in this session.`
|
||||
};
|
||||
}
|
||||
|
||||
return { allowed: true };
|
||||
}
|
||||
|
||||
/**
|
||||
* Activate a mode
|
||||
*
|
||||
* @param mode - The mode to activate
|
||||
* @param sessionId - Session ID
|
||||
* @param context - Optional context to store with state
|
||||
* @returns true if activation was successful
|
||||
*/
|
||||
activateMode(mode: ExecutionMode, sessionId: string, context?: Record<string, unknown>): boolean {
|
||||
const config = MODE_CONFIGS[mode];
|
||||
|
||||
// Check if can start
|
||||
const canStart = this.canStartMode(mode, sessionId);
|
||||
if (!canStart.allowed) {
|
||||
this.log(`Cannot activate ${config.name}: ${canStart.message}`);
|
||||
return false;
|
||||
}
|
||||
|
||||
try {
|
||||
this.ensureModesDir();
|
||||
|
||||
const stateFile = this.getSessionStatePath(mode, sessionId);
|
||||
const stateDir = dirname(stateFile);
|
||||
if (!existsSync(stateDir)) {
|
||||
mkdirSync(stateDir, { recursive: true });
|
||||
}
|
||||
|
||||
const state = {
|
||||
[config.activeProperty]: true,
|
||||
session_id: sessionId,
|
||||
activatedAt: new Date().toISOString(),
|
||||
...context
|
||||
};
|
||||
|
||||
writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf-8');
|
||||
this.log(`Activated ${config.name} for session ${sessionId}`);
|
||||
return true;
|
||||
} catch (error) {
|
||||
this.log(`Failed to activate ${config.name}: ${(error as Error).message}`);
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Deactivate a mode
|
||||
*
|
||||
* @param mode - The mode to deactivate
|
||||
* @param sessionId - Session ID
|
||||
* @returns true if deactivation was successful
|
||||
*/
|
||||
deactivateMode(mode: ExecutionMode, sessionId: string): boolean {
|
||||
const config = MODE_CONFIGS[mode];
|
||||
|
||||
try {
|
||||
const stateFile = this.getSessionStatePath(mode, sessionId);
|
||||
|
||||
if (!existsSync(stateFile)) {
|
||||
return true; // Already inactive
|
||||
}
|
||||
|
||||
unlinkSync(stateFile);
|
||||
this.log(`Deactivated ${config.name} for session ${sessionId}`);
|
||||
return true;
|
||||
} catch (error) {
|
||||
this.log(`Failed to deactivate ${config.name}: ${(error as Error).message}`);
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear all state for a mode
|
||||
*
|
||||
* @param mode - The mode to clear
|
||||
* @param sessionId - Optional session ID (if provided, only clears session state)
|
||||
* @returns true if successful
|
||||
*/
|
||||
clearModeState(mode: ExecutionMode, sessionId?: string): boolean {
|
||||
let success = true;
|
||||
|
||||
if (sessionId) {
|
||||
// Clear session-scoped state only
|
||||
const sessionStateFile = this.getSessionStatePath(mode, sessionId);
|
||||
if (existsSync(sessionStateFile)) {
|
||||
try {
|
||||
unlinkSync(sessionStateFile);
|
||||
} catch {
|
||||
success = false;
|
||||
}
|
||||
}
|
||||
return success;
|
||||
}
|
||||
|
||||
// Clear all state for this mode
|
||||
const stateFile = this.getStateFilePath(mode);
|
||||
if (existsSync(stateFile)) {
|
||||
try {
|
||||
unlinkSync(stateFile);
|
||||
} catch {
|
||||
success = false;
|
||||
}
|
||||
}
|
||||
|
||||
// Also clear session-scoped states
|
||||
try {
|
||||
const sessionIds = this.listSessionIds();
|
||||
for (const sid of sessionIds) {
|
||||
const sessionFile = this.getSessionStatePath(mode, sid);
|
||||
if (existsSync(sessionFile)) {
|
||||
try {
|
||||
unlinkSync(sessionFile);
|
||||
} catch {
|
||||
success = false;
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Ignore errors scanning sessions
|
||||
}
|
||||
|
||||
return success;
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear all mode states (force clear)
|
||||
*
|
||||
* @returns true if all states were cleared
|
||||
*/
|
||||
clearAllModeStates(): boolean {
|
||||
let success = true;
|
||||
|
||||
for (const mode of Object.keys(MODE_CONFIGS) as ExecutionMode[]) {
|
||||
if (!this.clearModeState(mode)) {
|
||||
success = false;
|
||||
}
|
||||
}
|
||||
|
||||
return success;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Session Management
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Check if a mode is active in any session
|
||||
*
|
||||
* @param mode - The mode to check
|
||||
* @returns true if the mode is active in any session
|
||||
*/
|
||||
isModeActiveInAnySession(mode: ExecutionMode): boolean {
|
||||
// Check legacy path first
|
||||
if (this.isModeActive(mode)) {
|
||||
return true;
|
||||
}
|
||||
|
||||
// Scan all session dirs
|
||||
const sessionIds = this.listSessionIds();
|
||||
for (const sid of sessionIds) {
|
||||
if (this.isModeActive(mode, sid)) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all session IDs that have a specific mode active
|
||||
*
|
||||
* @param mode - The mode to check
|
||||
* @returns Array of session IDs with this mode active
|
||||
*/
|
||||
getActiveSessionsForMode(mode: ExecutionMode): string[] {
|
||||
const sessionIds = this.listSessionIds();
|
||||
return sessionIds.filter(sid => this.isModeActive(mode, sid));
|
||||
}
|
||||
|
||||
/**
|
||||
* List all session IDs that have mode state files
|
||||
*
|
||||
* @returns Array of session IDs
|
||||
*/
|
||||
listSessionIds(): string[] {
|
||||
const sessionsDir = join(this.modesDir, 'sessions');
|
||||
if (!existsSync(sessionsDir)) {
|
||||
return [];
|
||||
}
|
||||
|
||||
try {
|
||||
return readdirSync(sessionsDir, { withFileTypes: true })
|
||||
.filter(dirent => dirent.isDirectory())
|
||||
.map(dirent => dirent.name)
|
||||
.filter(name => this.isValidSessionId(name));
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Stale State Cleanup
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Clear stale session directories
|
||||
*
|
||||
* Removes session directories that have no recent activity.
|
||||
*
|
||||
* @param maxAgeMs - Maximum age in milliseconds (default: 24 hours)
|
||||
* @returns Array of removed session IDs
|
||||
*/
|
||||
clearStaleSessionDirs(maxAgeMs: number = 24 * 60 * 60 * 1000): string[] {
|
||||
const sessionsDir = join(this.modesDir, 'sessions');
|
||||
if (!existsSync(sessionsDir)) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const removed: string[] = [];
|
||||
const sessionIds = this.listSessionIds();
|
||||
|
||||
for (const sid of sessionIds) {
|
||||
const sessionDir = this.getSessionDir(sid);
|
||||
try {
|
||||
const files = readdirSync(sessionDir);
|
||||
|
||||
// Remove empty directories
|
||||
if (files.length === 0) {
|
||||
rmSync(sessionDir, { recursive: true, force: true });
|
||||
removed.push(sid);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Check modification time of any state file
|
||||
let newest = 0;
|
||||
for (const f of files) {
|
||||
const stat = statSync(join(sessionDir, f));
|
||||
if (stat.mtimeMs > newest) {
|
||||
newest = stat.mtimeMs;
|
||||
}
|
||||
}
|
||||
|
||||
// Remove if stale
|
||||
if (Date.now() - newest > maxAgeMs) {
|
||||
rmSync(sessionDir, { recursive: true, force: true });
|
||||
removed.push(sid);
|
||||
}
|
||||
} catch {
|
||||
// Skip on error
|
||||
}
|
||||
}
|
||||
|
||||
return removed;
|
||||
}
|
||||
|
||||
/**
|
||||
* Clean up stale markers (older than threshold)
|
||||
*
|
||||
* @returns Array of cleaned up session IDs
|
||||
*/
|
||||
cleanupStaleMarkers(): string[] {
|
||||
const cleaned: string[] = [];
|
||||
const sessionIds = this.listSessionIds();
|
||||
|
||||
for (const sid of sessionIds) {
|
||||
for (const mode of Object.keys(MODE_CONFIGS) as ExecutionMode[]) {
|
||||
const stateFile = this.getSessionStatePath(mode, sid);
|
||||
if (existsSync(stateFile)) {
|
||||
try {
|
||||
const content = readFileSync(stateFile, 'utf-8');
|
||||
const state = JSON.parse(content);
|
||||
|
||||
if (state.activatedAt) {
|
||||
const activatedAt = new Date(state.activatedAt).getTime();
|
||||
const age = Date.now() - activatedAt;
|
||||
|
||||
if (age > STALE_MARKER_THRESHOLD) {
|
||||
this.log(`Cleaning up stale ${mode} marker for session ${sid} (${Math.round(age / 60000)} min old)`);
|
||||
unlinkSync(stateFile);
|
||||
cleaned.push(sid);
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Skip invalid files
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return Array.from(new Set(cleaned)); // Remove duplicates
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Private: Utility Methods
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Get the state file path for a mode (legacy shared path)
|
||||
*/
|
||||
private getStateFilePath(mode: ExecutionMode): string {
|
||||
const config = MODE_CONFIGS[mode];
|
||||
return join(this.modesDir, config.stateFile);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the session-scoped state file path
|
||||
*/
|
||||
private getSessionStatePath(mode: ExecutionMode, sessionId: string): string {
|
||||
const config = MODE_CONFIGS[mode];
|
||||
return join(this.modesDir, 'sessions', sessionId, config.stateFile);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the session directory path
|
||||
*/
|
||||
private getSessionDir(sessionId: string): string {
|
||||
return join(this.modesDir, 'sessions', sessionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a JSON-based mode is active
|
||||
*/
|
||||
private isJsonModeActive(
|
||||
stateFile: string,
|
||||
config: ModeConfig,
|
||||
sessionId?: string
|
||||
): boolean {
|
||||
if (!existsSync(stateFile)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
try {
|
||||
const content = readFileSync(stateFile, 'utf-8');
|
||||
const state = JSON.parse(content);
|
||||
|
||||
// Validate session identity if sessionId provided
|
||||
if (sessionId && state.session_id && state.session_id !== sessionId) {
|
||||
return false;
|
||||
}
|
||||
|
||||
if (config.activeProperty) {
|
||||
return state[config.activeProperty] === true;
|
||||
}
|
||||
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate session ID format
|
||||
*/
|
||||
private isValidSessionId(sessionId: string): boolean {
|
||||
if (!sessionId || typeof sessionId !== 'string') {
|
||||
return false;
|
||||
}
|
||||
// Allow alphanumeric, hyphens, and underscores only
|
||||
const SAFE_SESSION_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,255}$/;
|
||||
return SAFE_SESSION_ID_PATTERN.test(sessionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Log a message if logging is enabled
|
||||
*/
|
||||
private log(message: string): void {
|
||||
if (this.enableLogging) {
|
||||
const timestamp = new Date().toISOString();
|
||||
console.log(`[ModeRegistry ${timestamp}] ${message}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Factory Function
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Create a ModeRegistryService instance
|
||||
*
|
||||
* @param projectPath - Project root path
|
||||
* @param enableLogging - Enable logging
|
||||
* @returns ModeRegistryService instance
|
||||
*/
|
||||
export function createModeRegistryService(
|
||||
projectPath: string,
|
||||
enableLogging?: boolean
|
||||
): ModeRegistryService {
|
||||
return new ModeRegistryService({ projectPath, enableLogging });
|
||||
}
|
||||
408
ccw/src/core/services/session-end-service.ts
Normal file
408
ccw/src/core/services/session-end-service.ts
Normal file
@@ -0,0 +1,408 @@
|
||||
/**
|
||||
* SessionEndService - Unified session end handling
|
||||
*
|
||||
* Provides centralized management for session-end tasks:
|
||||
* - Task registration with priority
|
||||
* - Async execution with error handling
|
||||
* - Built-in tasks: incremental-embedding, clustering, heat-scores
|
||||
*
|
||||
* Design:
|
||||
* - Best-effort execution (failures logged but don't block)
|
||||
* - Priority-based ordering
|
||||
* - Support for async background execution
|
||||
*/
|
||||
|
||||
// =============================================================================
|
||||
// Types
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* A task to be executed at session end
|
||||
*/
|
||||
export interface EndTask {
|
||||
/** Unique task type identifier */
|
||||
type: string;
|
||||
/** Task priority (higher = executed first) */
|
||||
priority: number;
|
||||
/** Whether to run asynchronously in background */
|
||||
async: boolean;
|
||||
/** Task handler function */
|
||||
handler: () => Promise<void>;
|
||||
/** Optional description */
|
||||
description?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Result of a task execution
|
||||
*/
|
||||
export interface TaskResult {
|
||||
/** Task type identifier */
|
||||
type: string;
|
||||
/** Whether the task succeeded */
|
||||
success: boolean;
|
||||
/** Execution duration in milliseconds */
|
||||
duration: number;
|
||||
/** Error message if failed */
|
||||
error?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Options for SessionEndService
|
||||
*/
|
||||
export interface SessionEndServiceOptions {
|
||||
/** Project root path */
|
||||
projectPath: string;
|
||||
/** Whether to log task execution */
|
||||
enableLogging?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Summary of session end execution
|
||||
*/
|
||||
export interface SessionEndSummary {
|
||||
/** Total tasks executed */
|
||||
totalTasks: number;
|
||||
/** Number of successful tasks */
|
||||
successful: number;
|
||||
/** Number of failed tasks */
|
||||
failed: number;
|
||||
/** Total execution time in milliseconds */
|
||||
totalDuration: number;
|
||||
/** Individual task results */
|
||||
results: TaskResult[];
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Built-in Task Types
|
||||
// =============================================================================
|
||||
|
||||
/** Task type for incremental vector embedding */
|
||||
export const TASK_INCREMENTAL_EMBEDDING = 'incremental-embedding';
|
||||
|
||||
/** Task type for incremental clustering */
|
||||
export const TASK_INCREMENTAL_CLUSTERING = 'incremental-clustering';
|
||||
|
||||
/** Task type for heat score updates */
|
||||
export const TASK_HEAT_SCORE_UPDATE = 'heat-score-update';
|
||||
|
||||
// =============================================================================
|
||||
// SessionEndService
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Service for managing and executing session-end tasks
|
||||
*
|
||||
* This service provides a unified interface for registering and executing
|
||||
* background tasks when a session ends. Tasks are executed best-effort
|
||||
* with proper error handling and logging.
|
||||
*/
|
||||
export class SessionEndService {
|
||||
private projectPath: string;
|
||||
private enableLogging: boolean;
|
||||
private tasks: Map<string, EndTask> = new Map();
|
||||
|
||||
constructor(options: SessionEndServiceOptions) {
|
||||
this.projectPath = options.projectPath;
|
||||
this.enableLogging = options.enableLogging ?? false;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Task Registration
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Register a session-end task
|
||||
*
|
||||
* @param task - Task to register
|
||||
* @returns true if task was registered (false if type already exists)
|
||||
*/
|
||||
registerEndTask(task: EndTask): boolean {
|
||||
if (this.tasks.has(task.type)) {
|
||||
this.log(`Task "${task.type}" already registered, skipping`);
|
||||
return false;
|
||||
}
|
||||
|
||||
this.tasks.set(task.type, task);
|
||||
this.log(`Registered task "${task.type}" with priority ${task.priority}`);
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Unregister a session-end task
|
||||
*
|
||||
* @param type - Task type to unregister
|
||||
* @returns true if task was removed
|
||||
*/
|
||||
unregisterEndTask(type: string): boolean {
|
||||
const removed = this.tasks.delete(type);
|
||||
if (removed) {
|
||||
this.log(`Unregistered task "${type}"`);
|
||||
}
|
||||
return removed;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a task type is registered
|
||||
*
|
||||
* @param type - Task type to check
|
||||
* @returns true if task is registered
|
||||
*/
|
||||
hasTask(type: string): boolean {
|
||||
return this.tasks.has(type);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all registered task types
|
||||
*
|
||||
* @returns Array of task types
|
||||
*/
|
||||
getRegisteredTasks(): string[] {
|
||||
return Array.from(this.tasks.keys());
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Task Execution
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Execute all registered session-end tasks
|
||||
*
|
||||
* Tasks are executed in priority order (highest first).
|
||||
* Failures are logged but don't prevent other tasks from running.
|
||||
*
|
||||
* @param sessionId - Session ID for context
|
||||
* @returns Summary of execution results
|
||||
*/
|
||||
async executeEndTasks(sessionId: string): Promise<SessionEndSummary> {
|
||||
const startTime = Date.now();
|
||||
const results: TaskResult[] = [];
|
||||
|
||||
// Sort tasks by priority (descending)
|
||||
const sortedTasks = Array.from(this.tasks.values()).sort(
|
||||
(a, b) => b.priority - a.priority
|
||||
);
|
||||
|
||||
this.log(`Executing ${sortedTasks.length} session-end tasks for session ${sessionId}`);
|
||||
|
||||
// Execute tasks concurrently
|
||||
const executionPromises = sortedTasks.map(async (task) => {
|
||||
const taskStart = Date.now();
|
||||
|
||||
try {
|
||||
this.log(`Starting task "${task.type}"...`);
|
||||
await task.handler();
|
||||
|
||||
const duration = Date.now() - taskStart;
|
||||
this.log(`Task "${task.type}" completed in ${duration}ms`);
|
||||
|
||||
return {
|
||||
type: task.type,
|
||||
success: true,
|
||||
duration
|
||||
} as TaskResult;
|
||||
} catch (err) {
|
||||
const duration = Date.now() - taskStart;
|
||||
const errorMessage = (err as Error).message || 'Unknown error';
|
||||
this.log(`Task "${task.type}" failed: ${errorMessage}`);
|
||||
|
||||
return {
|
||||
type: task.type,
|
||||
success: false,
|
||||
duration,
|
||||
error: errorMessage
|
||||
} as TaskResult;
|
||||
}
|
||||
});
|
||||
|
||||
// Wait for all tasks to complete
|
||||
const taskResults = await Promise.allSettled(executionPromises);
|
||||
|
||||
// Collect results
|
||||
for (const result of taskResults) {
|
||||
if (result.status === 'fulfilled') {
|
||||
results.push(result.value);
|
||||
} else {
|
||||
// This shouldn't happen as we catch errors inside the task
|
||||
results.push({
|
||||
type: 'unknown',
|
||||
success: false,
|
||||
duration: 0,
|
||||
error: result.reason?.message || 'Task promise rejected'
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
const totalDuration = Date.now() - startTime;
|
||||
const successful = results.filter((r) => r.success).length;
|
||||
const failed = results.length - successful;
|
||||
|
||||
this.log(
|
||||
`Session-end tasks completed: ${successful}/${results.length} successful, ` +
|
||||
`${totalDuration}ms total`
|
||||
);
|
||||
|
||||
return {
|
||||
totalTasks: results.length,
|
||||
successful,
|
||||
failed,
|
||||
totalDuration,
|
||||
results
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute only async (background) tasks
|
||||
*
|
||||
* This is useful for fire-and-forget background processing.
|
||||
*
|
||||
* @param sessionId - Session ID for context
|
||||
* @returns Promise that resolves immediately (tasks run in background)
|
||||
*/
|
||||
executeBackgroundTasks(sessionId: string): void {
|
||||
const asyncTasks = Array.from(this.tasks.values())
|
||||
.filter((t) => t.async)
|
||||
.sort((a, b) => b.priority - a.priority);
|
||||
|
||||
if (asyncTasks.length === 0) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Fire-and-forget
|
||||
Promise.all(
|
||||
asyncTasks.map(async (task) => {
|
||||
try {
|
||||
this.log(`Background task "${task.type}" starting...`);
|
||||
await task.handler();
|
||||
this.log(`Background task "${task.type}" completed`);
|
||||
} catch (err) {
|
||||
this.log(`Background task "${task.type}" failed: ${(err as Error).message}`);
|
||||
}
|
||||
})
|
||||
).catch(() => {
|
||||
// Ignore errors - background tasks are best-effort
|
||||
});
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public: Built-in Tasks
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Register built-in session-end tasks
|
||||
*
|
||||
* This registers the standard tasks:
|
||||
* - incremental-embedding (priority 100)
|
||||
* - incremental-clustering (priority 50)
|
||||
* - heat-score-update (priority 25)
|
||||
*
|
||||
* @param sessionId - Session ID for context
|
||||
*/
|
||||
async registerBuiltinTasks(sessionId: string): Promise<void> {
|
||||
// Try to import and register embedding task
|
||||
try {
|
||||
const { isUnifiedEmbedderAvailable, UnifiedVectorIndex } = await import(
|
||||
'../unified-vector-index.js'
|
||||
);
|
||||
const { getMemoryMdContent } = await import('../memory-consolidation-pipeline.js');
|
||||
|
||||
if (isUnifiedEmbedderAvailable()) {
|
||||
this.registerEndTask({
|
||||
type: TASK_INCREMENTAL_EMBEDDING,
|
||||
priority: 100,
|
||||
async: true,
|
||||
description: 'Index new/updated content in vector store',
|
||||
handler: async () => {
|
||||
const vectorIndex = new UnifiedVectorIndex(this.projectPath);
|
||||
const memoryContent = getMemoryMdContent(this.projectPath);
|
||||
if (memoryContent) {
|
||||
await vectorIndex.indexContent(memoryContent, {
|
||||
source_id: 'MEMORY_MD',
|
||||
source_type: 'core_memory',
|
||||
category: 'core_memory'
|
||||
});
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
} catch {
|
||||
// Embedding dependencies not available
|
||||
this.log('Embedding task not registered: dependencies not available');
|
||||
}
|
||||
|
||||
// Try to import and register clustering task
|
||||
try {
|
||||
const { SessionClusteringService } = await import('../session-clustering-service.js');
|
||||
|
||||
this.registerEndTask({
|
||||
type: TASK_INCREMENTAL_CLUSTERING,
|
||||
priority: 50,
|
||||
async: true,
|
||||
description: 'Cluster unclustered sessions',
|
||||
handler: async () => {
|
||||
const clusteringService = new SessionClusteringService(this.projectPath);
|
||||
await clusteringService.autocluster({ scope: 'unclustered' });
|
||||
}
|
||||
});
|
||||
} catch {
|
||||
this.log('Clustering task not registered: dependencies not available');
|
||||
}
|
||||
|
||||
// Try to import and register heat score task
|
||||
try {
|
||||
const { getMemoryStore } = await import('../memory-store.js');
|
||||
|
||||
this.registerEndTask({
|
||||
type: TASK_HEAT_SCORE_UPDATE,
|
||||
priority: 25,
|
||||
async: true,
|
||||
description: 'Update entity heat scores',
|
||||
handler: async () => {
|
||||
const memoryStore = getMemoryStore(this.projectPath);
|
||||
const hotEntities = memoryStore.getHotEntities(50);
|
||||
for (const entity of hotEntities) {
|
||||
if (entity.id != null) {
|
||||
memoryStore.calculateHeatScore(entity.id);
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
} catch {
|
||||
this.log('Heat score task not registered: dependencies not available');
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Private: Utility Methods
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Log a message if logging is enabled
|
||||
*/
|
||||
private log(message: string): void {
|
||||
if (this.enableLogging) {
|
||||
console.log(`[SessionEndService] ${message}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Factory Function
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Create a SessionEndService instance with built-in tasks
|
||||
*
|
||||
* @param projectPath - Project root path
|
||||
* @param sessionId - Session ID for context
|
||||
* @param enableLogging - Whether to enable logging
|
||||
* @returns SessionEndService instance with built-in tasks registered
|
||||
*/
|
||||
export async function createSessionEndService(
|
||||
projectPath: string,
|
||||
sessionId: string,
|
||||
enableLogging = false
|
||||
): Promise<SessionEndService> {
|
||||
const service = new SessionEndService({ projectPath, enableLogging });
|
||||
await service.registerBuiltinTasks(sessionId);
|
||||
return service;
|
||||
}
|
||||
330
ccw/src/core/services/session-state-service.ts
Normal file
330
ccw/src/core/services/session-state-service.ts
Normal file
@@ -0,0 +1,330 @@
|
||||
/**
|
||||
* SessionStateService - Unified session state management
|
||||
*
|
||||
* Provides centralized session state persistence across CLI hooks and API routes.
|
||||
* Supports both legacy global path (~/.claude/.ccw-sessions/) and session-scoped
|
||||
* paths (.workflow/sessions/{sessionId}/) for workflow integration.
|
||||
*/
|
||||
|
||||
import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync } from 'fs';
|
||||
import { join, dirname } from 'path';
|
||||
import { homedir } from 'os';
|
||||
|
||||
/**
|
||||
* Session state interface
|
||||
*/
|
||||
export interface SessionState {
|
||||
/** ISO timestamp of first session load */
|
||||
firstLoad: string;
|
||||
/** Number of times session has been loaded */
|
||||
loadCount: number;
|
||||
/** Last prompt text (optional) */
|
||||
lastPrompt?: string;
|
||||
/** Active mode for the session (optional) */
|
||||
activeMode?: 'analysis' | 'write' | 'review' | 'auto';
|
||||
}
|
||||
|
||||
/**
|
||||
* Storage type for session state
|
||||
*/
|
||||
export type SessionStorageType = 'global' | 'session-scoped';
|
||||
|
||||
/**
|
||||
* Options for session state operations
|
||||
*/
|
||||
export interface SessionStateOptions {
|
||||
/** Storage type: 'global' uses ~/.claude/.ccw-sessions/, 'session-scoped' uses .workflow/sessions/{sessionId}/ */
|
||||
storageType?: SessionStorageType;
|
||||
/** Project root path (required for session-scoped storage) */
|
||||
projectPath?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates that a session ID is safe to use in file paths.
|
||||
* Session IDs should be alphanumeric with optional hyphens and underscores.
|
||||
* This prevents path traversal attacks (e.g., "../../../etc").
|
||||
*
|
||||
* @param sessionId - The session ID to validate
|
||||
* @returns true if the session ID is safe, false otherwise
|
||||
*/
|
||||
export function validateSessionId(sessionId: string): boolean {
|
||||
if (!sessionId || typeof sessionId !== 'string') {
|
||||
return false;
|
||||
}
|
||||
// Allow alphanumeric, hyphens, and underscores only
|
||||
// Must be 1-256 characters (reasonable length limit)
|
||||
// Must not start with a dot (hidden files) or hyphen
|
||||
const SAFE_SESSION_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,255}$/;
|
||||
return SAFE_SESSION_ID_PATTERN.test(sessionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the default global session state directory
|
||||
* Uses ~/.claude/.ccw-sessions/ for reliable persistence across sessions
|
||||
*/
|
||||
function getGlobalStateDir(): string {
|
||||
return join(homedir(), '.claude', '.ccw-sessions');
|
||||
}
|
||||
|
||||
/**
|
||||
* Get session state file path
|
||||
*
|
||||
* Supports two storage modes:
|
||||
* - 'global': ~/.claude/.ccw-sessions/session-{sessionId}.json (default)
|
||||
* - 'session-scoped': {projectPath}/.workflow/sessions/{sessionId}/state.json
|
||||
*
|
||||
* @param sessionId - The session ID
|
||||
* @param options - Storage options
|
||||
* @returns Full path to the session state file
|
||||
*/
|
||||
export function getSessionStatePath(sessionId: string, options?: SessionStateOptions): string {
|
||||
if (!validateSessionId(sessionId)) {
|
||||
throw new Error(`Invalid session ID: ${sessionId}`);
|
||||
}
|
||||
|
||||
const storageType = options?.storageType ?? 'global';
|
||||
|
||||
if (storageType === 'session-scoped') {
|
||||
if (!options?.projectPath) {
|
||||
throw new Error('projectPath is required for session-scoped storage');
|
||||
}
|
||||
const stateDir = join(options.projectPath, '.workflow', 'sessions', sessionId);
|
||||
if (!existsSync(stateDir)) {
|
||||
mkdirSync(stateDir, { recursive: true });
|
||||
}
|
||||
return join(stateDir, 'state.json');
|
||||
}
|
||||
|
||||
// Global storage (default)
|
||||
const stateDir = getGlobalStateDir();
|
||||
if (!existsSync(stateDir)) {
|
||||
mkdirSync(stateDir, { recursive: true });
|
||||
}
|
||||
return join(stateDir, `session-${sessionId}.json`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Load session state from file
|
||||
*
|
||||
* @param sessionId - The session ID
|
||||
* @param options - Storage options
|
||||
* @returns SessionState if exists and valid, null otherwise
|
||||
*/
|
||||
export function loadSessionState(sessionId: string, options?: SessionStateOptions): SessionState | null {
|
||||
if (!validateSessionId(sessionId)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
try {
|
||||
const stateFile = getSessionStatePath(sessionId, options);
|
||||
if (!existsSync(stateFile)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const content = readFileSync(stateFile, 'utf-8');
|
||||
const parsed = JSON.parse(content) as SessionState;
|
||||
|
||||
// Validate required fields
|
||||
if (typeof parsed.firstLoad !== 'string' || typeof parsed.loadCount !== 'number') {
|
||||
return null;
|
||||
}
|
||||
|
||||
return parsed;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Save session state to file
|
||||
*
|
||||
* @param sessionId - The session ID
|
||||
* @param state - The session state to save
|
||||
* @param options - Storage options
|
||||
*/
|
||||
export function saveSessionState(sessionId: string, state: SessionState, options?: SessionStateOptions): void {
|
||||
if (!validateSessionId(sessionId)) {
|
||||
throw new Error(`Invalid session ID: ${sessionId}`);
|
||||
}
|
||||
|
||||
const stateFile = getSessionStatePath(sessionId, options);
|
||||
|
||||
// Ensure parent directory exists
|
||||
const stateDir = dirname(stateFile);
|
||||
if (!existsSync(stateDir)) {
|
||||
mkdirSync(stateDir, { recursive: true });
|
||||
}
|
||||
|
||||
writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf-8');
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear session state (for session-end cleanup)
|
||||
*
|
||||
* @param sessionId - The session ID
|
||||
* @param options - Storage options
|
||||
* @returns true if state was cleared, false if it didn't exist
|
||||
*/
|
||||
export function clearSessionState(sessionId: string, options?: SessionStateOptions): boolean {
|
||||
if (!validateSessionId(sessionId)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
try {
|
||||
const stateFile = getSessionStatePath(sessionId, options);
|
||||
|
||||
if (!existsSync(stateFile)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
unlinkSync(stateFile);
|
||||
|
||||
// For session-scoped storage, also remove the session directory if empty
|
||||
if (options?.storageType === 'session-scoped' && options.projectPath) {
|
||||
const sessionDir = join(options.projectPath, '.workflow', 'sessions', sessionId);
|
||||
try {
|
||||
// Try to remove the directory (will fail if not empty)
|
||||
rmSync(sessionDir, { recursive: false, force: true });
|
||||
} catch {
|
||||
// Directory not empty or other error - ignore
|
||||
}
|
||||
}
|
||||
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Update session state with new values
|
||||
*
|
||||
* This is a convenience function that loads existing state, merges with updates,
|
||||
* and saves the result.
|
||||
*
|
||||
* @param sessionId - The session ID
|
||||
* @param updates - Partial state to merge
|
||||
* @param options - Storage options
|
||||
* @returns The updated state
|
||||
*/
|
||||
export function updateSessionState(
|
||||
sessionId: string,
|
||||
updates: Partial<SessionState>,
|
||||
options?: SessionStateOptions
|
||||
): SessionState {
|
||||
const existing = loadSessionState(sessionId, options);
|
||||
|
||||
const newState: SessionState = existing
|
||||
? { ...existing, ...updates }
|
||||
: {
|
||||
firstLoad: new Date().toISOString(),
|
||||
loadCount: 1,
|
||||
...updates
|
||||
};
|
||||
|
||||
saveSessionState(sessionId, newState, options);
|
||||
return newState;
|
||||
}
|
||||
|
||||
/**
|
||||
* Increment the load count for a session
|
||||
*
|
||||
* This is a convenience function for the common pattern of tracking
|
||||
* how many times a session has been loaded.
|
||||
*
|
||||
* @param sessionId - The session ID
|
||||
* @param prompt - Optional prompt to record as lastPrompt
|
||||
* @param options - Storage options
|
||||
* @returns Object with isFirstPrompt flag and updated state
|
||||
*/
|
||||
export function incrementSessionLoad(
|
||||
sessionId: string,
|
||||
prompt?: string,
|
||||
options?: SessionStateOptions
|
||||
): { isFirstPrompt: boolean; state: SessionState } {
|
||||
const existing = loadSessionState(sessionId, options);
|
||||
const isFirstPrompt = !existing;
|
||||
|
||||
const state: SessionState = isFirstPrompt
|
||||
? {
|
||||
firstLoad: new Date().toISOString(),
|
||||
loadCount: 1,
|
||||
lastPrompt: prompt
|
||||
}
|
||||
: {
|
||||
...existing,
|
||||
loadCount: existing.loadCount + 1,
|
||||
...(prompt !== undefined && { lastPrompt: prompt })
|
||||
};
|
||||
|
||||
saveSessionState(sessionId, state, options);
|
||||
return { isFirstPrompt, state };
|
||||
}
|
||||
|
||||
/**
|
||||
* SessionStateService class for object-oriented usage
|
||||
*/
|
||||
export class SessionStateService {
|
||||
private options?: SessionStateOptions;
|
||||
|
||||
constructor(options?: SessionStateOptions) {
|
||||
this.options = options;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get session state file path
|
||||
*/
|
||||
getStatePath(sessionId: string): string {
|
||||
return getSessionStatePath(sessionId, this.options);
|
||||
}
|
||||
|
||||
/**
|
||||
* Load session state
|
||||
*/
|
||||
load(sessionId: string): SessionState | null {
|
||||
return loadSessionState(sessionId, this.options);
|
||||
}
|
||||
|
||||
/**
|
||||
* Save session state
|
||||
*/
|
||||
save(sessionId: string, state: SessionState): void {
|
||||
saveSessionState(sessionId, state, this.options);
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear session state
|
||||
*/
|
||||
clear(sessionId: string): boolean {
|
||||
return clearSessionState(sessionId, this.options);
|
||||
}
|
||||
|
||||
/**
|
||||
* Update session state
|
||||
*/
|
||||
update(sessionId: string, updates: Partial<SessionState>): SessionState {
|
||||
return updateSessionState(sessionId, updates, this.options);
|
||||
}
|
||||
|
||||
/**
|
||||
* Increment load count
|
||||
*/
|
||||
incrementLoad(sessionId: string, prompt?: string): { isFirstPrompt: boolean; state: SessionState } {
|
||||
return incrementSessionLoad(sessionId, prompt, this.options);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if session is first load
|
||||
*/
|
||||
isFirstLoad(sessionId: string): boolean {
|
||||
return this.load(sessionId) === null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get load count for session
|
||||
*/
|
||||
getLoadCount(sessionId: string): number {
|
||||
const state = this.load(sessionId);
|
||||
return state?.loadCount ?? 0;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user