mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-09-30 12:39:42 +02:00
perf: implement phase 1-3 performance optimizations
Add implementation plans and code structure analysis for a 3-phase performance optimization effort. Refactor core modules to reduce timer overhead, consolidate regex usage, extract exec timeout config, add debouncer utility, and streamline server/schema validation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
arkon
@@ -0,0 +1,951 @@
|
||||
# Code Structure & Quality Findings
|
||||
|
||||
**Date**: 2026-02-28
|
||||
**Scope**: Full codebase analysis across 5 dimensions: frontend, backend, TypeScript, testing, and utilities/config.
|
||||
|
||||
This document contains detailed findings for agent teams to write implementation plans and execute improvements. Each section includes severity, specific locations, and recommended fixes.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Critical: server.ts God Object (6,736 LOC)](#1-critical-serverts-god-object)
|
||||
2. [Critical: app.js Monolith (15,196 LOC)](#2-critical-appjs-monolith)
|
||||
3. [Critical: CleanupManager Unused Despite Existing](#3-critical-cleanupmanager-unused)
|
||||
4. [High: Duplicated Debounce/Timer Patterns](#4-high-duplicated-debouncetimer-patterns)
|
||||
5. [High: Large Domain Files Need Splitting](#5-high-large-domain-files-need-splitting)
|
||||
6. [High: types.ts God File (1,443 LOC)](#6-high-typests-god-file)
|
||||
7. [High: Zod Schemas Duplicate TypeScript Types](#7-high-zod-schemas-duplicate-typescript-types)
|
||||
8. [High: Test Coverage Gaps](#8-high-test-coverage-gaps)
|
||||
9. [High: Duplicated Test Mocks](#9-high-duplicated-test-mocks)
|
||||
10. [Medium: Hardcoded Magic Values](#10-medium-hardcoded-magic-values)
|
||||
11. [Medium: Frontend Global State Monolith](#11-medium-frontend-global-state-monolith)
|
||||
12. [Medium: Frontend Code Duplication](#12-medium-frontend-code-duplication)
|
||||
13. [Medium: Inconsistent Logging](#13-medium-inconsistent-logging)
|
||||
14. [Medium: Utils Barrel Export Gaps](#14-medium-utils-barrel-export-gaps)
|
||||
15. [Medium: Non-Null Assertion Risks](#15-medium-non-null-assertion-risks)
|
||||
16. [Low: Dead Utility Functions](#16-low-dead-utility-functions)
|
||||
17. [Low: No Dependency Injection for File I/O](#17-low-no-dependency-injection-for-file-io)
|
||||
18. [Scorecard & Prioritized Roadmap](#18-scorecard--prioritized-roadmap)
|
||||
|
||||
---
|
||||
|
||||
## 1. Critical: server.ts God Object
|
||||
|
||||
**File**: `src/web/server.ts` (6,736 lines)
|
||||
**Severity**: CRITICAL
|
||||
**Impact**: Hardest file to maintain, test, and extend. Imports 38 modules.
|
||||
|
||||
### Problem
|
||||
|
||||
The `WebServer` class handles everything: HTTP routing (~110 routes), authentication, SSE broadcasting, terminal data batching, state persistence, session lifecycle, respawn orchestration, file serving, tunnel management, plan orchestration, and subagent coordination.
|
||||
|
||||
**Key metrics**:
|
||||
- 40+ private properties (Maps, timers, caches)
|
||||
- 70+ methods
|
||||
- `setupRoutes()` is 2,000+ LOC of inline route handlers
|
||||
- Zero test coverage
|
||||
|
||||
### Current Structure (Bad)
|
||||
|
||||
```
|
||||
WebServer class (6,736 LOC)
|
||||
├── Auth session management (lines 469, 668-698)
|
||||
├── SSE client management (lines 407-408, 5843-5880)
|
||||
├── Terminal data batching (lines 414-416, 5909-5966)
|
||||
├── Task update batching (line 426, 5995-6028)
|
||||
├── State persistence batching (lines 429-430, 6028-6061)
|
||||
├── Respawn lifecycle (lines 445-451, 5425-5534)
|
||||
├── Session cleanup (lines 4769-4961)
|
||||
├── Listener setup (lines 544-643)
|
||||
└── setupRoutes() (lines 645+, 2000+ LOC)
|
||||
├── /api/sessions/* (30+ routes inline)
|
||||
├── /api/respawn/* (7 routes inline)
|
||||
├── /api/subagents/* (7 routes inline)
|
||||
├── /api/plan/* (5 routes inline)
|
||||
├── /api/push/* (4 routes inline)
|
||||
└── ... 60+ more inline
|
||||
```
|
||||
|
||||
### Recommended Structure
|
||||
|
||||
```
|
||||
src/web/
|
||||
├── server.ts (~500 LOC - HTTP setup, route registration only)
|
||||
├── routes/
|
||||
│ ├── session-routes.ts (session CRUD, input, resize)
|
||||
│ ├── respawn-routes.ts (respawn control endpoints)
|
||||
│ ├── subagent-routes.ts (background agent tracking)
|
||||
│ ├── plan-routes.ts (plan generation & management)
|
||||
│ ├── push-routes.ts (web push subscriptions)
|
||||
│ ├── mux-routes.ts (tmux management)
|
||||
│ ├── case-routes.ts (case management)
|
||||
│ ├── file-routes.ts (file browsing/serving)
|
||||
│ └── system-routes.ts (status, stats, config, settings)
|
||||
├── middleware/
|
||||
│ ├── auth.ts (Basic Auth + session cookies)
|
||||
│ └── error-handler.ts (centralized error responses)
|
||||
└── services/
|
||||
├── sse-manager.ts (SSE client + broadcast)
|
||||
├── terminal-batcher.ts (60fps terminal batching)
|
||||
└── session-lifecycle.ts (listener setup/teardown)
|
||||
```
|
||||
|
||||
### Duplication in server.ts
|
||||
|
||||
**Error response pattern** repeated 189 times:
|
||||
```typescript
|
||||
return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
|
||||
```
|
||||
|
||||
**Fix**: Extract `findSessionOrFail()` middleware:
|
||||
```typescript
|
||||
const findSessionOrFail = (sessionId: string) => {
|
||||
const session = this.sessions.get(sessionId);
|
||||
if (!session) throw new NotFoundError('Session not found');
|
||||
return session;
|
||||
};
|
||||
```
|
||||
|
||||
**Event listener setup** copy-pasted for subagent watcher, image watcher, and team watcher (lines 544-643). Same attach/detach pattern duplicated 3 times.
|
||||
|
||||
---
|
||||
|
||||
## 2. Critical: app.js Monolith
|
||||
|
||||
**File**: `src/web/public/app.js` (15,196 lines)
|
||||
**Severity**: CRITICAL
|
||||
**Impact**: Untestable, hard to navigate, tightly coupled systems.
|
||||
|
||||
### Extractable Modules (by priority)
|
||||
|
||||
| Module | Lines | Current Location | Impact |
|
||||
|--------|-------|------------------|--------|
|
||||
| Mobile handlers (MobileDetection, KeyboardHandler, SwipeHandler) | ~300 | lines 168-620 | High |
|
||||
| Voice input (DeepgramProvider, VoiceInput) | ~830 | lines 631-1471 | High |
|
||||
| NotificationManager | ~450 | lines 2218-2663 | High |
|
||||
| xterm-zerolag-input (inlined copy from packages/) | ~400 | lines 1756-2153 | High |
|
||||
| KeyboardAccessoryBar | ~195 | lines 1480-1680 | Medium |
|
||||
| FocusTrap | ~60 | lines 1690-1748 | Medium |
|
||||
|
||||
### CodemanApp Class (12,000+ LOC)
|
||||
|
||||
The main `CodemanApp` class starting at line 2665 has:
|
||||
- **60+ Maps/Sets** in the constructor (lines 2667-2805)
|
||||
- **18 Map instances** with complex cross-references (subagents, parents, teams, windows)
|
||||
- **10+ monolithic methods** exceeding 100 lines each
|
||||
|
||||
**Largest methods**:
|
||||
| Method | Lines | Size |
|
||||
|--------|-------|------|
|
||||
| `renderAppSettings()` | 14400-14700 | ~300 LOC |
|
||||
| `selectSession()` | 6028-6250 | ~220 LOC |
|
||||
| `batchTerminalWrite()` | 7482-7700 | ~200 LOC |
|
||||
| `renderSessionTabs()` | 5814-6000 | ~180 LOC |
|
||||
| `openSubagentWindow()` | 11927-12100 | ~170 LOC |
|
||||
| `handleInit()` | 5183-5350 | ~170 LOC |
|
||||
|
||||
### Recommended Split
|
||||
|
||||
```
|
||||
src/web/public/
|
||||
├── app.js (~4000 LOC - core app, session mgmt, SSE)
|
||||
├── mobile.js (~300 LOC - MobileDetection, KeyboardHandler, SwipeHandler)
|
||||
├── voice.js (~830 LOC - DeepgramProvider, VoiceInput)
|
||||
├── notifications.js (~450 LOC - NotificationManager)
|
||||
├── keyboard-accessory.js (~200 LOC - KeyboardAccessoryBar)
|
||||
├── api-client.js (~100 LOC - fetch wrapper with error handling)
|
||||
└── config.js (~50 LOC - magic numbers, z-index layers)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Critical: CleanupManager Unused
|
||||
|
||||
**File**: `src/utils/cleanup-manager.ts` (320 lines)
|
||||
**Severity**: CRITICAL
|
||||
**Impact**: Memory leak risk. Well-designed utility exists but is never used. Every file manages cleanup manually.
|
||||
|
||||
### Current State
|
||||
|
||||
`CleanupManager` is exported from the utils barrel but has **0 instantiations** in production code. Instead, every file implements manual cleanup:
|
||||
|
||||
**respawn-controller.ts** (worst offender):
|
||||
```typescript
|
||||
// 11 timer properties, manually cleared in stop()
|
||||
private stepTimer: NodeJS.Timeout | null = null;
|
||||
private completionConfirmTimer: NodeJS.Timeout | null = null;
|
||||
private noOutputTimer: NodeJS.Timeout | null = null;
|
||||
// ... 8 more
|
||||
|
||||
stop() {
|
||||
if (this.stepTimer) clearTimeout(this.stepTimer);
|
||||
if (this.completionConfirmTimer) clearTimeout(this.completionConfirmTimer);
|
||||
// ... 9 more clearTimeout/clearInterval calls
|
||||
}
|
||||
```
|
||||
|
||||
**Files that should use CleanupManager**:
|
||||
| File | Timer/Listener Count | Current Cleanup |
|
||||
|------|---------------------|-----------------|
|
||||
| `respawn-controller.ts` | 11 timers + intervals | 11 manual clearTimeout/clearInterval |
|
||||
| `web/server.ts` | 6+ timers, debounce map | Manual in stop(), some may leak |
|
||||
| `state-store.ts` | 2 debounce timers | Manual clearTimeout |
|
||||
| `push-store.ts` | 1 save timer | Manual clearTimeout |
|
||||
| `subagent-watcher.ts` | debounce map + watchers | Manual clear + close |
|
||||
| `ralph-tracker.ts` | 3 debounce timers | Manual clear |
|
||||
| `bash-tool-parser.ts` | 1 debounce timer | Manual clear |
|
||||
| `image-watcher.ts` | 1 debounce map | Manual clear |
|
||||
|
||||
### Fix
|
||||
|
||||
Migrate all timer management to use `CleanupManager`. Example for respawn-controller.ts:
|
||||
|
||||
```typescript
|
||||
// Before: 11 fields + 11 clearTimeout calls
|
||||
private stepTimer: NodeJS.Timeout | null = null;
|
||||
// ...
|
||||
|
||||
// After: 1 field, auto-cleanup
|
||||
private cleanup = new CleanupManager();
|
||||
|
||||
startStep() {
|
||||
this.cleanup.setTimeout(() => { ... }, 5000, 'step');
|
||||
}
|
||||
|
||||
stop() {
|
||||
this.cleanup.dispose(); // Clears everything
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. High: Duplicated Debounce/Timer Patterns
|
||||
|
||||
**Severity**: HIGH
|
||||
**Impact**: 8+ files implement debounce independently. Bug fixes need to be applied everywhere.
|
||||
|
||||
### Pattern Inventory
|
||||
|
||||
```typescript
|
||||
// Pattern 1: Manual timer ref (used in 6 files)
|
||||
private saveTimer: NodeJS.Timeout | null = null;
|
||||
debouncedSave() {
|
||||
if (this.saveTimer) clearTimeout(this.saveTimer);
|
||||
this.saveTimer = setTimeout(() => this.save(), 500);
|
||||
}
|
||||
|
||||
// Pattern 2: Timer Map (used in 3 files)
|
||||
private fileDebouncers = new Map<string, NodeJS.Timeout>();
|
||||
debounce(key: string) {
|
||||
const existing = this.fileDebouncers.get(key);
|
||||
if (existing) clearTimeout(existing);
|
||||
this.fileDebouncers.set(key, setTimeout(() => { ... }, 100));
|
||||
}
|
||||
|
||||
// Pattern 3: State flag (used in 2 files)
|
||||
private isSaving = false;
|
||||
```
|
||||
|
||||
### Locations
|
||||
|
||||
| File | Debounce Vars | Delay (ms) |
|
||||
|------|---------------|------------|
|
||||
| `state-store.ts` | `saveTimeout`, `ralphStateSaveTimeout` | 500 |
|
||||
| `push-store.ts` | `saveTimer` | 500 |
|
||||
| `web/server.ts` | `persistDebounceTimers` (Map) | 500 |
|
||||
| `subagent-watcher.ts` | `fileDebouncers` (Map) | 100 |
|
||||
| `ralph-tracker.ts` | 3 debounce timers | 50, 30000 |
|
||||
| `bash-tool-parser.ts` | `EVENT_DEBOUNCE_MS` | 50 |
|
||||
| `image-watcher.ts` | debounce map | 200 |
|
||||
| `respawn-controller.ts` | 11 timer fields | various |
|
||||
|
||||
### Fix
|
||||
|
||||
Create a `Debouncer` utility:
|
||||
|
||||
```typescript
|
||||
// src/utils/debouncer.ts
|
||||
export class Debouncer {
|
||||
private timer: NodeJS.Timeout | null = null;
|
||||
|
||||
constructor(private readonly delayMs: number) {}
|
||||
|
||||
run(fn: () => void): void {
|
||||
if (this.timer) clearTimeout(this.timer);
|
||||
this.timer = setTimeout(fn, this.delayMs);
|
||||
}
|
||||
|
||||
cancel(): void {
|
||||
if (this.timer) clearTimeout(this.timer);
|
||||
this.timer = null;
|
||||
}
|
||||
}
|
||||
|
||||
// Usage:
|
||||
private saveDeb = new Debouncer(500);
|
||||
this.saveDeb.run(() => this.save());
|
||||
// cleanup: this.saveDeb.cancel();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. High: Large Domain Files Need Splitting
|
||||
|
||||
**Severity**: HIGH
|
||||
**Impact**: Complex state machines spanning 3,000+ lines are hard to understand and test.
|
||||
|
||||
### ralph-tracker.ts (3,905 LOC)
|
||||
|
||||
**5 responsibilities mixed**:
|
||||
1. Output Parsing (~900 LOC) - Line-by-line parsing, state extraction
|
||||
2. Todo Management (~700 LOC) - Parsing, dedup, expiry
|
||||
3. Plan Tracking (~800 LOC) - Enhanced plan tasks, checkpoints
|
||||
4. Circuit Breaker (~400 LOC) - State machine for stuck detection
|
||||
5. File Watching (~300 LOC) - Monitor external state files
|
||||
|
||||
**Recommended split**:
|
||||
```
|
||||
ralph-tracker.ts (core output parsing, ~1200 LOC)
|
||||
ralph-todo-manager.ts (todo parsing + management, ~700 LOC)
|
||||
ralph-plan-tracker.ts (plan tasks + checkpoints, ~800 LOC)
|
||||
ralph-circuit-breaker.ts (circuit breaker logic, ~400 LOC)
|
||||
```
|
||||
|
||||
### respawn-controller.ts (3,611 LOC)
|
||||
|
||||
**6 responsibilities mixed**:
|
||||
1. State Machine (~1,000 LOC) - 6+ states, transitions
|
||||
2. Idle Detection (~800 LOC) - 5 layers + multi-signal combining
|
||||
3. AI Checkers (~600 LOC) - Idle + plan checkers integration
|
||||
4. Health Scoring (~500 LOC) - Metrics, circuit breaker, scoring
|
||||
5. Action Logging (~300 LOC) - Timeline, detection status
|
||||
6. Stuck-State Detection (~250 LOC) - Timeout tracking
|
||||
|
||||
**Recommended split**:
|
||||
```
|
||||
respawn-controller.ts (state machine core, ~1000 LOC)
|
||||
respawn-idle-detection.ts (all 5 idle detection layers, ~800 LOC)
|
||||
respawn-health-scorer.ts (metrics & health scoring, ~500 LOC)
|
||||
```
|
||||
|
||||
### session.ts (2,418 LOC)
|
||||
|
||||
**8 responsibilities mixed**:
|
||||
1. PTY Management (~600 LOC)
|
||||
2. Terminal I/O (~400 LOC)
|
||||
3. Token Tracking (~200 LOC)
|
||||
4. Task Tracking (~250 LOC)
|
||||
5. Ralph Integration (~200 LOC)
|
||||
6. Auto-Clear/Compact (~300 LOC)
|
||||
7. Image Watching (~100 LOC)
|
||||
8. CLI Detection (~150 LOC)
|
||||
|
||||
**Recommended split**:
|
||||
```
|
||||
session.ts (PTY + terminal I/O core, ~1000 LOC)
|
||||
session-tracking.ts (token + task + Ralph, ~500 LOC)
|
||||
session-auto-ops.ts (auto-clear/compact + image, ~300 LOC)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. High: types.ts God File
|
||||
|
||||
**File**: `src/types.ts` (1,443 lines, 72 exported definitions)
|
||||
**Severity**: HIGH
|
||||
**Impact**: Every file imports from types.ts. Hard to find relevant types.
|
||||
|
||||
### Current Contents
|
||||
|
||||
- 46 interfaces
|
||||
- 25 types
|
||||
- 1 enum (ApiErrorCode)
|
||||
- 9 factory functions (createInitialState, etc.)
|
||||
|
||||
### Recommended Split
|
||||
|
||||
```
|
||||
src/types/
|
||||
├── index.ts (barrel export - transparent migration)
|
||||
├── session.ts (SessionState, SessionConfig, SessionMode, SessionColor)
|
||||
├── task.ts (TaskState, TaskDefinition, TaskStatus)
|
||||
├── respawn.ts (RespawnConfig, RespawnState, CircuitBreakerStatus)
|
||||
├── ralph.ts (RalphLoopState, RalphTrackerState, RalphTodoItem)
|
||||
├── api.ts (ApiResponse, ApiErrorCode, HookEventType, all route types)
|
||||
├── lifecycle.ts (LifecycleEventType, LifecycleEntry)
|
||||
└── common.ts (Disposable, BufferConfig, CleanupResourceType)
|
||||
```
|
||||
|
||||
The barrel export makes this a transparent refactor - existing `import from './types'` continues to work.
|
||||
|
||||
---
|
||||
|
||||
## 7. High: Zod Schemas Duplicate TypeScript Types
|
||||
|
||||
**File**: `src/web/schemas.ts` (508 lines)
|
||||
**Severity**: HIGH
|
||||
**Impact**: When a type changes, the Zod schema must be manually updated too. Source of bugs.
|
||||
|
||||
### Problem
|
||||
|
||||
Zod schemas manually duplicate TypeScript interfaces. **Zero `z.infer` usage found.**
|
||||
|
||||
```typescript
|
||||
// types.ts (manual interface)
|
||||
export interface CreateSessionRequest {
|
||||
workingDir?: string;
|
||||
mode?: SessionMode;
|
||||
name?: string;
|
||||
}
|
||||
|
||||
// schemas.ts (manual Zod schema - duplicated!)
|
||||
export const CreateSessionSchema = z.object({
|
||||
workingDir: safePathSchema.optional(),
|
||||
mode: z.enum(['claude', 'shell', 'opencode']).optional(),
|
||||
name: z.string().max(100).optional(),
|
||||
});
|
||||
```
|
||||
|
||||
### Fix
|
||||
|
||||
Use `z.infer` to derive TypeScript types from Zod schemas (single source of truth):
|
||||
|
||||
```typescript
|
||||
// schemas.ts
|
||||
export const CreateSessionSchema = z.object({
|
||||
workingDir: safePathSchema.optional(),
|
||||
mode: z.enum(['claude', 'shell', 'opencode']).optional(),
|
||||
name: z.string().max(100).optional(),
|
||||
});
|
||||
|
||||
// types.ts (auto-derived)
|
||||
export type CreateSessionRequest = z.infer<typeof CreateSessionSchema>;
|
||||
```
|
||||
|
||||
**Affected schemas** (~10):
|
||||
- CreateSessionSchema
|
||||
- RunPromptSchema
|
||||
- ResizeSchema
|
||||
- CreateCaseSchema
|
||||
- QuickStartSchema
|
||||
- HookEventSchema
|
||||
- RespawnConfigSchema
|
||||
- ConfigUpdateSchema
|
||||
- SettingsUpdateSchema
|
||||
|
||||
---
|
||||
|
||||
## 8. High: Test Coverage Gaps
|
||||
|
||||
**Severity**: HIGH
|
||||
**Impact**: Critical code paths untested. Regressions go unnoticed.
|
||||
|
||||
### Untested Source Files
|
||||
|
||||
| File | Lines | Risk |
|
||||
|------|-------|------|
|
||||
| `src/web/server.ts` | 6,736 | CRITICAL - Core REST API, 280+ routes |
|
||||
| `src/plan-orchestrator.ts` | ~500 | HIGH - Multi-agent plan generation |
|
||||
| `src/tunnel-manager.ts` | ~200 | MEDIUM - Cloudflare tunnel |
|
||||
| `src/session-lifecycle-log.ts` | ~150 | MEDIUM - JSONL audit log |
|
||||
| `src/ai-plan-checker.ts` | ~300 | MEDIUM - Plan completion detection |
|
||||
| `src/templates/claude-md.ts` | ~200 | LOW - CLAUDE.md generation |
|
||||
| `src/utils/claude-cli-resolver.ts` | ~100 | LOW - CLI path resolution |
|
||||
| `src/utils/opencode-cli-resolver.ts` | ~100 | LOW - OpenCode CLI support |
|
||||
| `src/utils/regex-patterns.ts` | ~100 | LOW - Used everywhere! |
|
||||
| `src/utils/token-validation.ts` | ~50 | LOW - Token counting |
|
||||
|
||||
### Test Quality Issues
|
||||
|
||||
**10 "not.toThrow()" tests without behavior verification**:
|
||||
```typescript
|
||||
// BAD: Only checks it doesn't crash
|
||||
expect(() => tracker.processMessage(null)).not.toThrow();
|
||||
|
||||
// GOOD: Also verify defensive behavior
|
||||
expect(() => tracker.processMessage(null)).not.toThrow();
|
||||
expect(tracker.getAllTasks().size).toBe(0);
|
||||
```
|
||||
|
||||
Locations:
|
||||
- `task-tracker.test.ts` - 5 instances
|
||||
- `image-watcher.test.ts` - 1 instance
|
||||
- `task-queue.test.ts` - 1 instance
|
||||
- Others scattered
|
||||
|
||||
---
|
||||
|
||||
## 9. High: Duplicated Test Mocks
|
||||
|
||||
**Severity**: HIGH
|
||||
**Impact**: Mock changes need updating in 4 places. Inconsistent mock behavior.
|
||||
|
||||
### MockSession Defined 4 Times
|
||||
|
||||
| File | Usage |
|
||||
|------|-------|
|
||||
| `test/respawn-controller.test.ts` | Full mock with event emitter |
|
||||
| `test/session-manager.test.ts` | Simpler mock |
|
||||
| `test/respawn-team-awareness.test.ts` | Copy of respawn-controller mock |
|
||||
| `test/respawn-test-utils.ts` | **Comprehensive mock - UNUSED!** |
|
||||
|
||||
### MockStateStore Defined 2 Times
|
||||
|
||||
| File | Usage |
|
||||
|------|-------|
|
||||
| `test/session-manager.test.ts` | Basic mock |
|
||||
| `test/ralph-loop.test.ts` | Separate implementation |
|
||||
|
||||
### Unused Test Utilities
|
||||
|
||||
`test/respawn-test-utils.ts` exports these utilities that **no test file imports**:
|
||||
- `createTimeController()` - Abstraction over vitest fake timers
|
||||
- `MockAiIdleChecker` - Fully mocked AI idle checker
|
||||
- `MockAiPlanChecker` - Fully mocked plan checker
|
||||
- Factory functions for pre-configured controllers
|
||||
|
||||
### Fix
|
||||
|
||||
Create `test/mocks/` directory:
|
||||
```
|
||||
test/
|
||||
├── mocks/
|
||||
│ ├── mock-session.ts (single MockSession, used everywhere)
|
||||
│ ├── mock-state-store.ts (single MockStateStore)
|
||||
│ └── index.ts (barrel export)
|
||||
├── utils/
|
||||
│ └── time-controller.ts (from respawn-test-utils.ts)
|
||||
└── ... test files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Medium: Hardcoded Magic Values
|
||||
|
||||
**Severity**: MEDIUM
|
||||
**Impact**: Hard to tune, inconsistent when same value appears in multiple places.
|
||||
|
||||
### Already Centralized (Good)
|
||||
|
||||
- `src/config/buffer-limits.ts` - All buffer sizes
|
||||
- `src/config/map-limits.ts` - All collection limits
|
||||
|
||||
### NOT Centralized (40+ values scattered)
|
||||
|
||||
**In server.ts** (lines 145-194):
|
||||
```typescript
|
||||
const TASK_UPDATE_BATCH_INTERVAL = 100;
|
||||
const STATE_UPDATE_DEBOUNCE_INTERVAL = 500;
|
||||
const SESSIONS_LIST_CACHE_TTL = 1000;
|
||||
const SCHEDULED_CLEANUP_INTERVAL = 5 * 60 * 1000;
|
||||
const SSE_HEALTH_CHECK_INTERVAL = 30 * 1000;
|
||||
const MAX_TERMINAL_COLS = 500;
|
||||
const MAX_TERMINAL_ROWS = 200;
|
||||
const AUTH_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
|
||||
const MAX_AUTH_SESSIONS = 100;
|
||||
const AUTH_FAILURE_WINDOW_MS = 15 * 60 * 1000;
|
||||
const STATS_COLLECTION_INTERVAL_MS = 2000;
|
||||
const MAX_INPUT_LENGTH = 64 * 1024;
|
||||
```
|
||||
|
||||
**In hooks-config.ts**: `timeout: 10000` hardcoded 6 times.
|
||||
|
||||
**In respawn-controller.ts** (lines 538-565): 10 timing constants.
|
||||
|
||||
**In utils**: `EXEC_TIMEOUT_MS = 5000` duplicated in both `claude-cli-resolver.ts` and `opencode-cli-resolver.ts`.
|
||||
|
||||
**In app.js**:
|
||||
```javascript
|
||||
// line 27: 600000 - stuck detection threshold
|
||||
// line 24: 5000 - default scrollback
|
||||
// lines 34-35: 128*1024, 256*1024 - chunk sizes
|
||||
// lines 152-155: 150, 100 - keyboard detection thresholds
|
||||
// lines 573-575: 80, 300, 100 - swipe detection params
|
||||
```
|
||||
|
||||
### Fix
|
||||
|
||||
Create additional config files:
|
||||
```
|
||||
src/config/
|
||||
├── buffer-limits.ts (existing)
|
||||
├── map-limits.ts (existing)
|
||||
├── server-config.ts (NEW - web server intervals, auth, caching)
|
||||
├── timing-config.ts (NEW - debounce delays, check intervals)
|
||||
└── terminal-config.ts (NEW - max cols/rows, batch intervals)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Medium: Frontend Global State Monolith
|
||||
|
||||
**Severity**: MEDIUM
|
||||
**Impact**: All state in single CodemanApp class. Tight coupling between unrelated systems.
|
||||
|
||||
### 60+ State Variables in CodemanApp Constructor (lines 2667-2805)
|
||||
|
||||
```javascript
|
||||
this.sessions = new Map(); // Session data
|
||||
this.subagents = new Map(); // Agent tracking
|
||||
this.subagentActivity = new Map(); // Tool call tracking
|
||||
this.subagentToolResults = new Map(); // Result caching
|
||||
this.subagentParentMap = new Map(); // Agent-to-session mapping
|
||||
this.teams = new Map(); // Team tracking
|
||||
this.teamTasks = new Map(); // Team task state
|
||||
this.planSubagents = new Map(); // Plan agent tracking
|
||||
this.pendingWrites = []; // Terminal write queue
|
||||
this.terminalBufferCache = new Map(); // Buffer caching (unbounded!)
|
||||
this.projectInsights = new Map(); // Bash tool insights
|
||||
// ... 40+ more
|
||||
```
|
||||
|
||||
### Problems
|
||||
|
||||
1. **18 Map instances** with complex cross-references (no garbage collection strategy)
|
||||
2. **No domain separation**: Session, subagent, notification, UI, and network state mixed
|
||||
3. **Implicit dependencies**: `selectSession()` requires 5+ Maps to be in consistent state
|
||||
4. **`terminalBufferCache`** has no max size - can grow unbounded with many sessions
|
||||
|
||||
### Recommended Domain Split
|
||||
|
||||
```javascript
|
||||
// Instead of 60+ flat properties:
|
||||
class SessionState {
|
||||
sessions = new Map();
|
||||
sessionOrder = [];
|
||||
terminalBuffers = new Map();
|
||||
tabAlerts = new Map();
|
||||
}
|
||||
|
||||
class SubagentState {
|
||||
subagents = new Map();
|
||||
activity = new Map();
|
||||
parentMap = new Map();
|
||||
windows = new Map();
|
||||
minimized = new Map();
|
||||
}
|
||||
|
||||
class TeamState {
|
||||
teams = new Map();
|
||||
tasks = new Map();
|
||||
teammates = new Map();
|
||||
}
|
||||
|
||||
class UIState {
|
||||
activeSessionId = null;
|
||||
draggedTabId = null;
|
||||
isLoadingBuffer = false;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Medium: Frontend Code Duplication
|
||||
|
||||
**Severity**: MEDIUM
|
||||
**Impact**: Repeated patterns increase maintenance burden and inconsistency risk.
|
||||
|
||||
### Duplicated Patterns
|
||||
|
||||
**API fetch calls** (~50 instances):
|
||||
```javascript
|
||||
// Repeated everywhere:
|
||||
fetch(`/api/sessions/${sessionId}/...`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({...})
|
||||
}).catch(() => {})
|
||||
```
|
||||
**Fix**: Extract `ApiClient` class.
|
||||
|
||||
**`innerHTML` usage** (104 instances):
|
||||
- Mix of template strings, createElement chains, and direct innerHTML
|
||||
- Some with manual XSS escaping (`text.replace(/</g, '<')`), some without
|
||||
- No consistent DOM creation pattern
|
||||
|
||||
**`typeof app !== 'undefined'` checks** (20+ instances):
|
||||
- Lines 458, 467, 481, 614, 617, 1549, etc.
|
||||
- **Fix**: Ensure `app` is always defined as global singleton.
|
||||
|
||||
**Element visibility toggling** (212+ occurrences):
|
||||
```javascript
|
||||
element.classList.add('active')
|
||||
element.classList.remove('active')
|
||||
```
|
||||
**Fix**: Create `toggleClass(el, className, condition)` utility.
|
||||
|
||||
### Event Listener Issues
|
||||
|
||||
- **152 `addEventListener` calls** with fragile cleanup
|
||||
- **Mix of inline (`onclick="app.method()"`) and addEventListener** - hard to track
|
||||
- **Element cache (`_elemCache`) never invalidated** if DOM elements are recreated (line 2808)
|
||||
- **Tab drag-and-drop listeners** may not clean up if user switches tabs mid-drag
|
||||
|
||||
---
|
||||
|
||||
## 13. Medium: Inconsistent Logging
|
||||
|
||||
**Severity**: MEDIUM
|
||||
**Impact**: Hard to debug in production. Can't filter by severity or component.
|
||||
|
||||
### Current State
|
||||
|
||||
- **345 console calls** across source files
|
||||
- **No structured logging** - all `console.log/error` directly
|
||||
- **No log levels** (DEBUG, INFO, WARN, ERROR)
|
||||
|
||||
### Inconsistent Prefixes
|
||||
|
||||
```typescript
|
||||
// Some files use brackets:
|
||||
console.log('[Session] Starting interactive...');
|
||||
console.log('[RalphLoop] Task assigned...');
|
||||
console.log('[TunnelManager] Tunnel started');
|
||||
|
||||
// Others use no prefix:
|
||||
console.error('Failed to spawn PTY:', err);
|
||||
console.log('Server listening on port', port);
|
||||
```
|
||||
|
||||
### Positive: CleanupManager Has Debug Mode
|
||||
|
||||
`src/utils/cleanup-manager.ts` has a `debugMode` flag for conditional debug logging - good pattern not replicated elsewhere.
|
||||
|
||||
### Fix
|
||||
|
||||
Either:
|
||||
1. Enforce consistent `[ComponentName]` prefixes via lint rule
|
||||
2. Create lightweight logger abstraction (not a heavy framework)
|
||||
|
||||
---
|
||||
|
||||
## 14. Medium: Utils Barrel Export Gaps
|
||||
|
||||
**File**: `src/utils/index.ts`
|
||||
**Severity**: MEDIUM
|
||||
**Impact**: Forces deep imports, unclear public API.
|
||||
|
||||
### Missing Exports
|
||||
|
||||
These functions are defined but NOT exported from the barrel:
|
||||
- `createAnsiPatternFull()` and `createAnsiPatternSimple()` (factory functions from `regex-patterns.ts`)
|
||||
- `SAFE_PATH_PATTERN` (from `regex-patterns.ts`)
|
||||
- `validateTokenCounts()` and `validateTokensAndCost()` (from `token-validation.ts`)
|
||||
- `isSimilar()`, `isSimilarByDistance()`, `levenshteinDistance()`, `normalizePhrase()` (from `string-similarity.ts` - though some are dead code, see finding #16)
|
||||
|
||||
### Deep Import Anti-Pattern (16 instances)
|
||||
|
||||
Some files bypass the barrel unnecessarily:
|
||||
```typescript
|
||||
// Could use barrel:
|
||||
import { BufferAccumulator } from './utils/buffer-accumulator.js';
|
||||
import { LRUMap } from './utils/lru-map.js';
|
||||
|
||||
// Must deep import (not in barrel):
|
||||
import { SAFE_PATH_PATTERN } from './utils/regex-patterns.js';
|
||||
```
|
||||
|
||||
### Fix
|
||||
|
||||
Add missing exports to `src/utils/index.ts` and update import sites.
|
||||
|
||||
---
|
||||
|
||||
## 15. Medium: Non-Null Assertion Risks
|
||||
|
||||
**Severity**: MEDIUM
|
||||
**Impact**: Runtime crashes if assumptions violated. 37 instances found.
|
||||
|
||||
### Distribution
|
||||
|
||||
| File | Count | Risk Level |
|
||||
|------|-------|------------|
|
||||
| `src/web/server.ts` | 10 | Low (auth flow verified) |
|
||||
| `src/session.ts` | 6 | **High** (mux/terminal refs) |
|
||||
| `src/respawn-controller.ts` | 4 | Low (config validated) |
|
||||
| `src/lru-map.ts` | 3 | Low (checked lookups) |
|
||||
| `src/subagent-watcher.ts` | 2 | Low (pending tool calls) |
|
||||
| Others | 12 | Low |
|
||||
|
||||
### High-Risk Examples (session.ts)
|
||||
|
||||
```typescript
|
||||
// Line 915 - _mux could be null if startInteractive called during cleanup
|
||||
`[Session] Starting interactive (with ${this._mux!.backend})`
|
||||
|
||||
// Line 954 - _muxSession could be null in race condition
|
||||
this._muxSession!.muxName
|
||||
```
|
||||
|
||||
### Fix
|
||||
|
||||
Add null guards before assertions, or document invariants:
|
||||
```typescript
|
||||
// Before:
|
||||
this._mux!.backend
|
||||
|
||||
// After:
|
||||
if (!this._mux) throw new Error('Invariant: _mux must be initialized before startInteractive');
|
||||
this._mux.backend
|
||||
```
|
||||
|
||||
### Positive Notes
|
||||
|
||||
- **0 instances of `as any`**
|
||||
- **0 instances of `@ts-ignore` or `@ts-expect-error`**
|
||||
- TypeScript overall score: 8.5/10
|
||||
|
||||
---
|
||||
|
||||
## 16. Low: Dead Utility Functions
|
||||
|
||||
**File**: `src/utils/string-similarity.ts`
|
||||
**Severity**: LOW
|
||||
**Impact**: Code clutter, confusion about what's actually used.
|
||||
|
||||
### Unused Functions
|
||||
|
||||
These are defined and exported but **never imported anywhere**:
|
||||
- `isSimilar(a, b, threshold)` - similarity check with threshold
|
||||
- `isSimilarByDistance(a, b, maxDistance)` - Levenshtein-based check
|
||||
- `levenshteinDistance(a, b)` - raw edit distance
|
||||
- `normalizePhrase(phrase)` - phrase normalization
|
||||
|
||||
### Actually Used
|
||||
|
||||
Only these are imported from the barrel:
|
||||
- `stringSimilarity()` - used in ralph-tracker.ts
|
||||
- `fuzzyPhraseMatch()` - used in ralph-tracker.ts
|
||||
- `todoContentHash()` - used in ralph-tracker.ts
|
||||
|
||||
### Fix
|
||||
|
||||
Delete unused functions or mark as `@internal` if kept for future use.
|
||||
|
||||
---
|
||||
|
||||
## 17. Low: No Dependency Injection for File I/O
|
||||
|
||||
**Severity**: LOW (practical impact limited at current scale)
|
||||
**Impact**: Can't mock filesystem for unit tests. 68+ hard-coded filesystem calls.
|
||||
|
||||
### Examples
|
||||
|
||||
```typescript
|
||||
// state-store.ts - directly imports and uses fs
|
||||
import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
|
||||
|
||||
// push-store.ts - hard-coded paths
|
||||
const KEYS_FILE = join(DATA_DIR, 'push-keys.json');
|
||||
const SUBS_FILE = join(DATA_DIR, 'push-subscriptions.json');
|
||||
|
||||
// ai-checker-base.ts - direct execSync
|
||||
execSync(`tmux kill-session -t "${this.checkMuxName}"`, { timeout: 3000 });
|
||||
```
|
||||
|
||||
### Why This Is Lower Priority
|
||||
|
||||
- The codebase uses integration tests (spawning real processes/tmux sessions) rather than unit tests
|
||||
- Most filesystem operations are in infrastructure code, not business logic
|
||||
- Adding DI would be a large refactor with limited near-term benefit
|
||||
|
||||
---
|
||||
|
||||
## 18. Scorecard & Prioritized Roadmap
|
||||
|
||||
### Overall Scores
|
||||
|
||||
| Category | Score | Notes |
|
||||
|----------|-------|-------|
|
||||
| TypeScript Safety | 8.5/10 | 0 `any`, 0 `@ts-ignore`, 37 non-null assertions |
|
||||
| Error Handling | 8/10 | Consistent helpers, proper type guards, no untyped catches |
|
||||
| Async/Promise Safety | 9.5/10 | Zero unhandled rejections, all async properly guarded |
|
||||
| Resource Cleanup | 7/10 | Good patterns but CleanupManager unused |
|
||||
| Module Organization | 5/10 | 3 god files, types.ts too large |
|
||||
| Test Coverage | 6/10 | Core logic tested, server.ts untested |
|
||||
| Config Centralization | 6/10 | Partially done, 40+ scattered values |
|
||||
| Frontend Architecture | 4/10 | 15K monolith, 60+ Maps, no modularity |
|
||||
| Code Duplication | 5/10 | Debounce patterns, fetch calls, mocks |
|
||||
|
||||
### Implementation Phases
|
||||
|
||||
**Phase 1 - Quick Wins (1-2 days)** ✅ COMPLETE
|
||||
1. ✅ Export missing functions from utils barrel (~30 min) — `createAnsiPatternFull`, `createAnsiPatternSimple`, `SAFE_PATH_PATTERN`, `validateTokenCounts`, `validateTokensAndCost` all now exported from `src/utils/index.ts`
|
||||
2. ✅ Delete dead utility functions (~15 min) — `isSimilar()` removed from `string-similarity.ts`; `levenshteinDistance()`, `isSimilarByDistance()`, `normalizePhrase()` made private (used internally by `fuzzyPhraseMatch`/`stringSimilarity`)
|
||||
3. ✅ Consolidate duplicated `EXEC_TIMEOUT_MS` constant (~15 min) — Created `src/config/exec-timeout.ts` as single source of truth; `claude-cli-resolver.ts`, `opencode-cli-resolver.ts`, and `tmux-manager.ts` all import from it
|
||||
4. ✅ Add `z.infer` to Zod schemas (~2 hours) — `src/web/schemas.ts` now has 36 `z.infer` type exports (lines 512-547) covering all schemas
|
||||
5. ✅ Fix 10 weak "not.toThrow()" tests (~1 hour) — All `not.toThrow()` calls now have behavior assertions: `task-tracker.test.ts` (6 instances all followed by state checks), `image-watcher.test.ts` (1 instance followed by length check), `session-manager.test.ts` (1 instance followed by count check)
|
||||
|
||||
**Phase 2 - CleanupManager & Debounce (2-3 days)** ✅ COMPLETE
|
||||
1. ✅ Create `Debouncer` utility class (~1 hour) — Created `src/utils/debouncer.ts` with `Debouncer` and `KeyedDebouncer` classes; exported from `src/utils/index.ts`
|
||||
2. ✅ Migrate 8 files from manual debounce to Debouncer (~3 hours) — `state-store.ts` (2 Debouncers), `push-store.ts` (1 Debouncer), `ralph-tracker.ts` (2 Debouncers), `bash-tool-parser.ts` (1 Debouncer), `image-watcher.ts` (1 KeyedDebouncer), `subagent-watcher.ts` (1 KeyedDebouncer), `server.ts` (1 KeyedDebouncer for persist timers)
|
||||
3. ✅ Migrate respawn-controller to CleanupManager (~3 hours) — 10 timer fields replaced with `CleanupManager` instance; `clearTimers()` now uses `cleanup.dispose()` with reinitialization for reuse
|
||||
4. ✅ Migrate server.ts timer cleanup to CleanupManager (~2 hours) — 5 standalone timers migrated to `CleanupManager`; terminal batch timers and pending respawn starts left as manual Maps (complex lifecycle)
|
||||
5. ✅ Migrate remaining files (~2 hours) — `ralph-tracker.ts` (watcher + stall timer → CleanupManager), `bash-tool-parser.ts` (auto-remove timers → CleanupManager), `subagent-watcher.ts` (intervals + watchers → CleanupManager); ~30 manual timer fields eliminated, ~200+ lines of boilerplate removed
|
||||
|
||||
**Phase 3 - server.ts Route Extraction (3-4 days)**
|
||||
1. Create `src/web/routes/` directory structure
|
||||
2. Extract session routes (~2 hours)
|
||||
3. Extract respawn routes (~1 hour)
|
||||
4. Extract subagent routes (~1 hour)
|
||||
5. Extract remaining route groups (~4 hours)
|
||||
6. Create auth middleware (~1 hour)
|
||||
7. Create error handler middleware (~1 hour)
|
||||
8. Reduce server.ts to ~1,500 LOC
|
||||
|
||||
**Phase 4 - Domain File Splitting (2-3 days)**
|
||||
1. Split types.ts into types/ directory (~2 hours)
|
||||
2. Split ralph-tracker.ts into 4 files (~4 hours)
|
||||
3. Split respawn-controller.ts into 3 files (~4 hours)
|
||||
4. Split session.ts into 3 files (~3 hours)
|
||||
|
||||
**Phase 5 - Frontend Modularization (3-4 days)**
|
||||
1. Extract mobile handlers to mobile.js (~2 hours)
|
||||
2. Extract voice input to voice.js (~3 hours)
|
||||
3. Extract NotificationManager to notifications.js (~2 hours)
|
||||
4. Extract KeyboardAccessoryBar (~1 hour)
|
||||
5. Create ApiClient wrapper (~2 hours)
|
||||
6. Create config.js for magic numbers (~1 hour)
|
||||
7. Remove inlined xterm-zerolag-input copy (~1 hour)
|
||||
|
||||
**Phase 6 - Config Consolidation (1 day)**
|
||||
1. Create `src/config/server-config.ts` (~1 hour)
|
||||
2. Create `src/config/timing-config.ts` (~1 hour)
|
||||
3. Move scattered constants from 10+ files (~3 hours)
|
||||
|
||||
**Phase 7 - Test Infrastructure (2-3 days)**
|
||||
1. Consolidate MockSession into single shared mock (~2 hours)
|
||||
2. Create `test/mocks/` with barrel export (~1 hour)
|
||||
3. Import unused respawn-test-utils where needed (~1 hour)
|
||||
4. Add server.ts route tests (ongoing, ~8+ hours)
|
||||
|
||||
---
|
||||
|
||||
## Appendix: File Size Inventory
|
||||
|
||||
| File | Lines | Category |
|
||||
|------|-------|----------|
|
||||
| `src/web/public/app.js` | 15,196 | Frontend |
|
||||
| `src/web/server.ts` | 6,736 | Backend |
|
||||
| `src/ralph-tracker.ts` | 3,905 | Domain |
|
||||
| `src/respawn-controller.ts` | 3,611 | Domain |
|
||||
| `src/session.ts` | 2,418 | Domain |
|
||||
| `src/subagent-watcher.ts` | 1,689 | Domain |
|
||||
| `src/types.ts` | 1,443 | Types |
|
||||
| `src/state-store.ts` | 910 | Infrastructure |
|
||||
| `src/ralph-loop.ts` | ~600 | Domain |
|
||||
| `src/web/schemas.ts` | 508 | Validation |
|
||||
| All other src/ files | <500 each | Various |
|
||||
|
||||
### What's Working Well
|
||||
|
||||
These patterns should be **preserved, not refactored**:
|
||||
- Clean one-way dependency graph (no circular deps)
|
||||
- EventEmitter-based decoupling between domain models
|
||||
- Proper `import type` usage (19 files, consistent)
|
||||
- Utility type adoption (101 instances of Record, Partial, Omit, etc.)
|
||||
- `assertNever()` for exhaustive switch checking
|
||||
- `StaleExpirationMap` and `LRUMap` for bounded collections
|
||||
- State persistence circuit breaker pattern
|
||||
- TypeScript strict mode with all safety flags enabled
|
||||
@@ -1,7 +1,7 @@
|
||||
# Performance & Responsiveness Optimization Plan
|
||||
|
||||
**Date**: 2026-02-28
|
||||
**Status**: In Progress
|
||||
**Status**: Phases 1–4 Complete. Phase 5 optional/deferred.
|
||||
|
||||
---
|
||||
|
||||
@@ -13,7 +13,7 @@ Three independent research passes analyzed the Codeman codebase for performance
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Quick Wins — ALREADY IMPLEMENTED
|
||||
## Phase 1: Quick Wins — COMPLETE
|
||||
|
||||
All Phase 1 items were found to already exist in the codebase during verification:
|
||||
|
||||
@@ -27,7 +27,7 @@ All Phase 1 items were found to already exist in the codebase during verificatio
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Frontend Responsiveness — MOSTLY ALREADY IMPLEMENTED
|
||||
## Phase 2: Frontend Responsiveness — COMPLETE
|
||||
|
||||
### 2.1 Batch `getBoundingClientRect()` in connection lines — DONE
|
||||
- **Files**: `src/web/public/app.js` (`_updateConnectionLinesImmediate()`)
|
||||
@@ -51,7 +51,7 @@ All Phase 1 items were found to already exist in the codebase during verificatio
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Backend Hot Paths
|
||||
## Phase 3: Backend Hot Paths — COMPLETE
|
||||
|
||||
### 3.1 State diff broadcasts — ALREADY OPTIMIZED
|
||||
- `broadcastSessionStateDebounced()` already batches at 500ms intervals
|
||||
@@ -84,35 +84,37 @@ All Phase 1 items were found to already exist in the codebase during verificatio
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: System-Level Improvements
|
||||
## Phase 4: System-Level Improvements — COMPLETE
|
||||
|
||||
### 4.1 Incremental state persistence
|
||||
- **Files**: `src/state-store.ts` (~lines 145-160)
|
||||
- **Problem**: Every 500ms debounce writes the entire `AppState` (all sessions, tasks, config) via `JSON.stringify()`. With 50 sessions, state can be tens of MB. Serialization alone costs 50-100ms.
|
||||
- **Fix**: Track dirty sessions. On persist, only re-serialize dirty sessions; cache serialized JSON for clean sessions. Assemble final output from cached fragments.
|
||||
- **Impact**: Reduces serialization cost from O(all sessions) to O(dirty sessions). Typical steady-state: 1-2 dirty sessions instead of 50.
|
||||
### 4.1 Incremental state persistence — DONE
|
||||
- **Files**: `src/state-store.ts` (`assembleStateJson()`, `setSession()`)
|
||||
- **Change**: Added `dirtySessions` Set and `cachedSessionJsons` Map. On persist, only dirty sessions are re-serialized; clean sessions reuse cached JSON fragments. `setSession()` marks sessions dirty; `assembleStateJson()` rebuilds only changed fragments.
|
||||
- **Impact**: Serialization cost reduced from O(all sessions) to O(dirty sessions). Typical steady-state: 1-2 dirty sessions instead of 50.
|
||||
|
||||
### 4.2 Replace polling with fs watchers for team watcher
|
||||
- **Files**: `src/team-watcher.ts` (~lines 148-180)
|
||||
- **Problem**: Polls `~/.claude/teams/` every 5s via `readdir()` + `stat()`. Blocks event loop for 100-200ms on large directories.
|
||||
- **Fix**: Use `chokidar` (already a dependency) or `fs.watch()` to react to changes. Keep a 30s fallback poll for reliability.
|
||||
- **Impact**: Eliminates 5s polling overhead; near-instant team detection.
|
||||
### 4.2 Replace polling with fs watchers for team watcher — DONE
|
||||
- **Files**: `src/team-watcher.ts` (`setupFsWatchers()`)
|
||||
- **Change**: Added chokidar watchers on both `~/.claude/teams/` and `~/.claude/tasks/` directories for instant event-driven detection. Lock files ignored via chokidar config. Mtime-based dedup skips unchanged files. Polling interval relaxed from 5s to 30s as a fallback.
|
||||
- **Impact**: Near-instant team detection; polling overhead eliminated for normal operation.
|
||||
|
||||
### 4.3 Consolidate subagent file watchers
|
||||
- **Files**: `src/subagent-watcher.ts` (~line 229+)
|
||||
- **Problem**: One chokidar watcher per agent directory. With 500 agents, that's 500 inotify watchers consuming kernel resources.
|
||||
- **Fix**: Watch at the session level (one watcher per session's subagent directory), not per-agent. Parse events to route to correct agent.
|
||||
- **Impact**: Reduces inotify watchers from 500 to ~50 (one per session).
|
||||
### 4.3 Consolidate subagent file watchers — DONE
|
||||
- **Files**: `src/subagent-watcher.ts` (`setupDirectoryWatcher()`)
|
||||
- **Change**: Replaced per-agent chokidar watchers with one `fs.watch()` per session subagent directory. Events are routed to the correct agent via filename. Per-file debouncing (100ms) prevents hammering on bulk discovery.
|
||||
- **Impact**: Inotify watchers reduced from potentially 500 (one per agent) to ~50 (one per session directory).
|
||||
|
||||
### 4.4 Stream transcript files instead of full reads
|
||||
- **Files**: `src/subagent-watcher.ts` (~lines 959-964)
|
||||
- **Problem**: `loadTranscript()` reads entire transcript file (can be >100KB). With 500 agents discovered at once, that's 50MB of file reads.
|
||||
- **Fix**: Only read last 10KB for display (tail). Full file on-demand only (e.g., when user opens transcript viewer).
|
||||
- **Impact**: Reduces file I/O from 50MB to 5MB for bulk agent discovery.
|
||||
### 4.4 Stream transcript files instead of full reads — DONE
|
||||
- **Files**: `src/subagent-watcher.ts` (`tailFile()`, `findDescriptionInAgentFile()`, parent transcript lookup)
|
||||
- **Change**: Multiple streaming strategies implemented:
|
||||
- **Live monitoring**: Position-based `tailFile()` with `createReadStream({ start: fromPosition })` — only reads new content
|
||||
- **Parent transcript lookup**: Streams only last 16KB (`createReadStream({ start: offset })`)
|
||||
- **Description extraction**: Streams only first 8KB, exits early after 5 lines
|
||||
- **Full read**: Only for on-demand transcript review panel (with optional `limit` parameter)
|
||||
- **Impact**: File I/O for bulk agent discovery reduced from ~50MB to ~5MB.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Long-Term Architectural (Optional)
|
||||
## Phase 5: Long-Term Architectural (Optional) — NOT STARTED
|
||||
|
||||
These items are deferred until scaling demands justify the complexity.
|
||||
|
||||
### 5.1 Worker thread for PTY processing
|
||||
- **Files**: `src/session.ts`
|
||||
@@ -134,42 +136,23 @@ All Phase 1 items were found to already exist in the codebase during verificatio
|
||||
|
||||
---
|
||||
|
||||
## Priority Matrix (Remaining Work)
|
||||
## Completion Summary
|
||||
|
||||
| # | Item | Impact | Risk | Effort |
|
||||
|---|------|--------|------|--------|
|
||||
| 3.1 | State diff broadcasts | **Very High** | Medium | 3-4h |
|
||||
| 3.2 | Fix session cache invalidation | **High** | Low | 1h |
|
||||
| 3.3 | Skip PTY processing for hidden sessions | **High** | Medium | 2-3h |
|
||||
| 3.5 | Throttle detection broadcasts | **Medium** | Low | 1h |
|
||||
| 3.4 | Batch liveness checks | **Medium** | Low | 1-2h |
|
||||
| 4.1 | Incremental state persistence | **Medium** | Medium | 3-4h |
|
||||
| 4.2 | Team watcher fs events | **Low-Med** | Medium | 2h |
|
||||
| 4.3 | Consolidate file watchers | **Low-Med** | Medium | 2h |
|
||||
| 4.4 | Stream transcripts | **Low-Med** | Low | 1h |
|
||||
| 5.1 | Worker thread PTY | **Med** (at scale) | High | 8h |
|
||||
| 5.2 | Per-session SSE subs | **Med** (at scale) | High | 4h |
|
||||
| 5.3 | O(1) LRUMap | **Very Low** | Medium | 2h |
|
||||
| Phase | Scope | Status | Items |
|
||||
|-------|-------|--------|-------|
|
||||
| 1 | Quick Wins | **Complete** | 5/5 (all pre-existing) |
|
||||
| 2 | Frontend Responsiveness | **Complete** | 3/3 actionable done, 2 skipped |
|
||||
| 3 | Backend Hot Paths | **Complete** | 4/4 actionable done, 1 deferred |
|
||||
| 4 | System-Level | **Complete** | 4/4 done |
|
||||
| 5 | Long-Term Architectural | **Not started** | 0/3 — deferred until needed |
|
||||
|
||||
---
|
||||
|
||||
## Recommended Execution Order
|
||||
|
||||
**Sprint 1** (Phase 3 — Backend Hot Paths): Items 3.1, 3.2, 3.3, 3.5
|
||||
- Backend serialization and broadcast efficiency
|
||||
- Highest remaining impact; requires careful testing with multiple active sessions
|
||||
|
||||
**Sprint 2** (Phase 4 — System Level): Items 4.1, 3.4, 4.3, 4.4
|
||||
- State persistence, liveness checks, watcher consolidation
|
||||
- Medium-complexity refactors
|
||||
|
||||
**Sprint 3** (Phase 5 — Architectural): Items 5.1, 5.2 — only if scaling demands it
|
||||
**Overall**: 16/16 actionable items complete. 3 optional items deferred.
|
||||
|
||||
---
|
||||
|
||||
## Measurement
|
||||
|
||||
Before starting implementation, establish baselines:
|
||||
Before starting Phase 5, establish baselines:
|
||||
|
||||
1. **Frontend**: Record Chrome DevTools Performance trace with 10 sessions open. Measure:
|
||||
- Frame rate during rapid terminal output
|
||||
|
||||
@@ -0,0 +1,738 @@
|
||||
# Phase 1 Implementation Plan: Quick Wins
|
||||
|
||||
**Source**: `docs/code-structure-findings.md` (Phase 1 - Quick Wins section)
|
||||
**Estimated effort**: 1-2 days
|
||||
**Tasks**: 5 independent tasks (can be done in parallel unless noted)
|
||||
|
||||
---
|
||||
|
||||
## Safety Constraints
|
||||
|
||||
Before starting ANY work, read and follow these rules:
|
||||
|
||||
1. **Never run `npx vitest run`** (full suite) -- it kills tmux sessions. You are running inside a Codeman-managed tmux session.
|
||||
2. **Run individual tests only**: `npx vitest run test/<file>.test.ts`
|
||||
3. **Never test on port 3000** -- the live dev server runs there. Tests use ports 3150+.
|
||||
4. **After TypeScript changes**: Run `tsc --noEmit` to verify type checking passes.
|
||||
5. **Before considering done**: Run `npm run lint` and `npm run format:check` to ensure CI passes.
|
||||
6. **Never kill tmux sessions** -- check `echo $CODEMAN_MUX` first.
|
||||
|
||||
---
|
||||
|
||||
## Task Dependencies
|
||||
|
||||
All 5 tasks are independent and can be done in parallel. However:
|
||||
- Task 1 (barrel exports) is a prerequisite if you want to update import sites to use the barrel after Task 3 (consolidate EXEC_TIMEOUT_MS). The EXEC_TIMEOUT_MS consolidation creates a new export that should be added to the barrel.
|
||||
- Task 2 (delete dead functions) removes functions that Task 1 would otherwise need to add to the barrel. Do Task 2 first or simultaneously with Task 1 to avoid adding exports for dead code.
|
||||
|
||||
**Recommended order**: Task 2 -> Task 1 -> Task 3 -> Task 4 -> Task 5
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Export Missing Functions from Utils Barrel
|
||||
|
||||
**File**: `src/utils/index.ts`
|
||||
**Time**: ~30 minutes
|
||||
|
||||
### Problem
|
||||
|
||||
The barrel file (`src/utils/index.ts`) is missing exports for several functions that are defined in util modules, forcing consumers to use deep imports or preventing usage entirely.
|
||||
|
||||
### Missing Exports
|
||||
|
||||
From `src/utils/regex-patterns.ts`:
|
||||
- `createAnsiPatternFull()` -- factory for fresh ANSI regex (documented in CLAUDE.md)
|
||||
- `createAnsiPatternSimple()` -- factory for fresh ANSI regex (documented in CLAUDE.md)
|
||||
- `stripAnsi()` -- ANSI stripping utility
|
||||
- `SAFE_PATH_PATTERN` -- regex for safe file paths (currently deep-imported by `schemas.ts` and `tmux-manager.ts`)
|
||||
|
||||
From `src/utils/token-validation.ts`:
|
||||
- `validateTokenCounts()` -- token count validation (documented in CLAUDE.md)
|
||||
- `validateTokensAndCost()` -- token + cost validation (documented in CLAUDE.md)
|
||||
|
||||
**Note**: Do NOT export `isSimilar`, `isSimilarByDistance`, `levenshteinDistance`, or `normalizePhrase` from `string-similarity.ts` -- these are dead code (see Task 2).
|
||||
|
||||
### Edit 1: Add missing regex-patterns exports
|
||||
|
||||
**File**: `src/utils/index.ts`
|
||||
|
||||
**Old code** (lines 13-18):
|
||||
```typescript
|
||||
export {
|
||||
ANSI_ESCAPE_PATTERN_FULL,
|
||||
ANSI_ESCAPE_PATTERN_SIMPLE,
|
||||
TOKEN_PATTERN,
|
||||
SPINNER_PATTERN,
|
||||
} from './regex-patterns.js';
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
export {
|
||||
ANSI_ESCAPE_PATTERN_FULL,
|
||||
ANSI_ESCAPE_PATTERN_SIMPLE,
|
||||
TOKEN_PATTERN,
|
||||
SPINNER_PATTERN,
|
||||
createAnsiPatternFull,
|
||||
createAnsiPatternSimple,
|
||||
stripAnsi,
|
||||
SAFE_PATH_PATTERN,
|
||||
} from './regex-patterns.js';
|
||||
```
|
||||
|
||||
### Edit 2: Add missing token-validation exports
|
||||
|
||||
**File**: `src/utils/index.ts`
|
||||
|
||||
**Old code** (line 19):
|
||||
```typescript
|
||||
export { MAX_SESSION_TOKENS } from './token-validation.js';
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
export { MAX_SESSION_TOKENS, validateTokenCounts, validateTokensAndCost } from './token-validation.js';
|
||||
```
|
||||
|
||||
### Optional follow-up: Update deep imports to use barrel
|
||||
|
||||
These files currently deep-import `SAFE_PATH_PATTERN` and could be updated to use the barrel instead:
|
||||
|
||||
- `src/web/schemas.ts` line 11: `import { SAFE_PATH_PATTERN } from '../utils/regex-patterns.js';` could become `import { SAFE_PATH_PATTERN } from '../utils/index.js';`
|
||||
- `src/tmux-manager.ts` line 44: `import { SAFE_PATH_PATTERN } from './utils/regex-patterns.js';` could become part of existing barrel import
|
||||
|
||||
This is a low-priority cosmetic change. The barrel export itself is the important fix.
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
tsc --noEmit
|
||||
npm run lint
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Delete Dead Utility Functions
|
||||
|
||||
**File**: `src/utils/string-similarity.ts`
|
||||
**Time**: ~15 minutes
|
||||
|
||||
### Problem
|
||||
|
||||
Four exported functions in `string-similarity.ts` are never imported anywhere in the codebase:
|
||||
- `levenshteinDistance()` (lines 27-69)
|
||||
- `isSimilar()` (lines 106-108)
|
||||
- `isSimilarByDistance()` (lines 123-125)
|
||||
- `normalizePhrase()` (lines 139-144)
|
||||
|
||||
Only three functions are actually used (all by `ralph-tracker.ts` via the barrel):
|
||||
- `stringSimilarity()` -- uses `levenshteinDistance()` internally
|
||||
- `fuzzyPhraseMatch()` -- uses `normalizePhrase()` and `isSimilarByDistance()` internally
|
||||
- `todoContentHash()`
|
||||
|
||||
### Strategy
|
||||
|
||||
`levenshteinDistance()` is called by `stringSimilarity()`, and `normalizePhrase()` and `isSimilarByDistance()` are called by `fuzzyPhraseMatch()`. So they cannot be deleted -- they just need to be un-exported (made private to the module).
|
||||
|
||||
`isSimilar()` is truly dead -- not called by anything. Delete it entirely.
|
||||
|
||||
### Edit 1: Remove `export` from `levenshteinDistance`
|
||||
|
||||
**File**: `src/utils/string-similarity.ts`
|
||||
|
||||
**Old code** (line 27):
|
||||
```typescript
|
||||
export function levenshteinDistance(a: string, b: string): number {
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
function levenshteinDistance(a: string, b: string): number {
|
||||
```
|
||||
|
||||
### Edit 2: Delete `isSimilar` function entirely
|
||||
|
||||
**File**: `src/utils/string-similarity.ts`
|
||||
|
||||
**Old code** (lines 94-108):
|
||||
```typescript
|
||||
/**
|
||||
* Check if two strings are similar within a given threshold.
|
||||
*
|
||||
* @param a - First string
|
||||
* @param b - Second string
|
||||
* @param threshold - Minimum similarity ratio (default: 0.85 = 85% similar)
|
||||
* @returns True if similarity >= threshold
|
||||
*
|
||||
* @example
|
||||
* isSimilar('COMPLETE', 'COMPLET', 0.85) // true (87.5% similar)
|
||||
* isSimilar('COMPLETE', 'DONE', 0.85) // false (0% similar)
|
||||
*/
|
||||
export function isSimilar(a: string, b: string, threshold = 0.85): boolean {
|
||||
return stringSimilarity(a, b) >= threshold;
|
||||
}
|
||||
```
|
||||
|
||||
**New code**: (delete entirely -- replace with empty string)
|
||||
|
||||
### Edit 3: Remove `export` from `isSimilarByDistance`
|
||||
|
||||
**File**: `src/utils/string-similarity.ts`
|
||||
|
||||
**Old code** (line 123):
|
||||
```typescript
|
||||
export function isSimilarByDistance(a: string, b: string, maxDistance = 2): boolean {
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
function isSimilarByDistance(a: string, b: string, maxDistance = 2): boolean {
|
||||
```
|
||||
|
||||
### Edit 4: Remove `export` from `normalizePhrase`
|
||||
|
||||
**File**: `src/utils/string-similarity.ts`
|
||||
|
||||
**Old code** (line 139):
|
||||
```typescript
|
||||
export function normalizePhrase(phrase: string): string {
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
function normalizePhrase(phrase: string): string {
|
||||
```
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
tsc --noEmit
|
||||
npx vitest run test/string-utilities.test.ts
|
||||
npm run lint
|
||||
```
|
||||
|
||||
Note: If `test/string-utilities.test.ts` imports any of the now-unexported functions, those test imports will fail. Check the test file and remove tests for `isSimilar` (deleted) and update any direct tests for `levenshteinDistance`, `isSimilarByDistance`, `normalizePhrase` to test them indirectly through the public API (`stringSimilarity`, `fuzzyPhraseMatch`), or remove those tests.
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Consolidate Duplicated `EXEC_TIMEOUT_MS` Constant
|
||||
|
||||
**Files**:
|
||||
- `src/utils/claude-cli-resolver.ts` (line 17)
|
||||
- `src/utils/opencode-cli-resolver.ts` (line 16)
|
||||
- `src/tmux-manager.ts` (line 63) -- also has its own copy
|
||||
|
||||
**Time**: ~15 minutes
|
||||
|
||||
### Problem
|
||||
|
||||
`EXEC_TIMEOUT_MS = 5000` is defined identically in three files. Changes need to happen in all three places.
|
||||
|
||||
### Strategy
|
||||
|
||||
Create a shared constant and export it. The natural home is a new config file since the existing config files (`buffer-limits.ts`, `map-limits.ts`) follow this pattern. However, to keep it minimal, we can add it to an existing config file or create a small one.
|
||||
|
||||
**Recommended approach**: Add to `src/config/timing-config.ts` (new file) as a single constant. This file can grow later in Phase 6 to hold other timing constants.
|
||||
|
||||
Alternatively, the simplest approach: export from one of the existing utils and import in the others. Since both CLI resolvers are in `src/utils/`, the cleanest approach is to put it in a shared location.
|
||||
|
||||
### Option A: Add to existing config (simpler)
|
||||
|
||||
Create `src/config/exec-timeout.ts`:
|
||||
|
||||
**New file**: `src/config/exec-timeout.ts`
|
||||
```typescript
|
||||
/**
|
||||
* Timeout for child process exec commands (e.g., `which claude`, `which opencode`, tmux commands).
|
||||
* Used across CLI resolvers and tmux manager.
|
||||
*/
|
||||
export const EXEC_TIMEOUT_MS = 5000;
|
||||
```
|
||||
|
||||
### Edit 1: Update `claude-cli-resolver.ts`
|
||||
|
||||
**File**: `src/utils/claude-cli-resolver.ts`
|
||||
|
||||
**Old code** (lines 11-17):
|
||||
```typescript
|
||||
import { execSync } from 'node:child_process';
|
||||
import { existsSync } from 'node:fs';
|
||||
import { delimiter, dirname, join } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
|
||||
/** Timeout for exec commands (5 seconds) */
|
||||
const EXEC_TIMEOUT_MS = 5000;
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
import { execSync } from 'node:child_process';
|
||||
import { existsSync } from 'node:fs';
|
||||
import { delimiter, dirname, join } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
|
||||
```
|
||||
|
||||
### Edit 2: Update `opencode-cli-resolver.ts`
|
||||
|
||||
**File**: `src/utils/opencode-cli-resolver.ts`
|
||||
|
||||
**Old code** (lines 10-16):
|
||||
```typescript
|
||||
import { execSync } from 'node:child_process';
|
||||
import { existsSync } from 'node:fs';
|
||||
import { dirname, join } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
|
||||
/** Timeout for exec commands (5 seconds) */
|
||||
const EXEC_TIMEOUT_MS = 5000;
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
import { execSync } from 'node:child_process';
|
||||
import { existsSync } from 'node:fs';
|
||||
import { dirname, join } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
|
||||
```
|
||||
|
||||
### Edit 3: Update `tmux-manager.ts`
|
||||
|
||||
**File**: `src/tmux-manager.ts`
|
||||
|
||||
**Old code** (line 63):
|
||||
```typescript
|
||||
const EXEC_TIMEOUT_MS = 5000;
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
import { EXEC_TIMEOUT_MS } from './config/exec-timeout.js';
|
||||
```
|
||||
|
||||
Note: `tmux-manager.ts` already has many imports at the top of the file. Add this import near the other local imports (around lines 43-56). The `const EXEC_TIMEOUT_MS = 5000;` on line 63 should be deleted entirely (replaced with the import).
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
tsc --noEmit
|
||||
npm run lint
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Add `z.infer` to Zod Schemas
|
||||
|
||||
**Files**:
|
||||
- `src/web/schemas.ts` (add type exports)
|
||||
- `src/types.ts` (replace manual interfaces with `z.infer` re-exports where applicable)
|
||||
|
||||
**Time**: ~2 hours
|
||||
|
||||
### Problem
|
||||
|
||||
All 30+ Zod schemas in `schemas.ts` define validation rules, but zero use `z.infer` to derive TypeScript types. Instead, `types.ts` manually duplicates interfaces that match the schemas. When a schema changes, the type must be manually updated too.
|
||||
|
||||
### Strategy
|
||||
|
||||
Add `z.infer` type exports to `schemas.ts` for each exported schema. This creates derived types as the single source of truth. For schemas that have corresponding manual interfaces in `types.ts`, the manual interface can be replaced with a re-export of the inferred type.
|
||||
|
||||
**Important**: Not all schemas have matching interfaces in `types.ts`. The `RespawnConfig` interface in `types.ts` (line 395) has all required fields, while `RespawnConfigSchema` has all optional fields (it's for partial updates). These are NOT the same type and should NOT be unified.
|
||||
|
||||
### Edit 1: Add inferred type exports to `schemas.ts`
|
||||
|
||||
**File**: `src/web/schemas.ts`
|
||||
|
||||
After each schema definition, add a corresponding type export. Add the following lines at the **end of the file** (after line 509):
|
||||
|
||||
**Old code** (end of file, lines 506-509):
|
||||
```typescript
|
||||
.optional(),
|
||||
});
|
||||
```
|
||||
|
||||
Wait -- the end of file is actually at line 509 after the `RalphLoopStartSchema`. Add the type exports after the last schema:
|
||||
|
||||
**Append to end of file** `src/web/schemas.ts`:
|
||||
|
||||
```typescript
|
||||
|
||||
// ========== Inferred Types ==========
|
||||
// Derive TypeScript types from Zod schemas (single source of truth)
|
||||
|
||||
export type CreateSessionInput = z.infer<typeof CreateSessionSchema>;
|
||||
export type RunPromptInput = z.infer<typeof RunPromptSchema>;
|
||||
export type ResizeInput = z.infer<typeof ResizeSchema>;
|
||||
export type CreateCaseInput = z.infer<typeof CreateCaseSchema>;
|
||||
export type QuickStartInput = z.infer<typeof QuickStartSchema>;
|
||||
export type HookEventInput = z.infer<typeof HookEventSchema>;
|
||||
export type RespawnConfigInput = z.infer<typeof RespawnConfigSchema>;
|
||||
export type ConfigUpdateInput = z.infer<typeof ConfigUpdateSchema>;
|
||||
export type SettingsUpdateInput = z.infer<typeof SettingsUpdateSchema>;
|
||||
export type SessionInputWithLimitInput = z.infer<typeof SessionInputWithLimitSchema>;
|
||||
export type SessionNameInput = z.infer<typeof SessionNameSchema>;
|
||||
export type SessionColorInput = z.infer<typeof SessionColorSchema>;
|
||||
export type RalphConfigInput = z.infer<typeof RalphConfigSchema>;
|
||||
export type FixPlanImportInput = z.infer<typeof FixPlanImportSchema>;
|
||||
export type RalphPromptWriteInput = z.infer<typeof RalphPromptWriteSchema>;
|
||||
export type AutoClearInput = z.infer<typeof AutoClearSchema>;
|
||||
export type AutoCompactInput = z.infer<typeof AutoCompactSchema>;
|
||||
export type ImageWatcherInput = z.infer<typeof ImageWatcherSchema>;
|
||||
export type FlickerFilterInput = z.infer<typeof FlickerFilterSchema>;
|
||||
export type QuickRunInput = z.infer<typeof QuickRunSchema>;
|
||||
export type ScheduledRunInput = z.infer<typeof ScheduledRunSchema>;
|
||||
export type LinkCaseInput = z.infer<typeof LinkCaseSchema>;
|
||||
export type GeneratePlanInput = z.infer<typeof GeneratePlanSchema>;
|
||||
export type GeneratePlanDetailedInput = z.infer<typeof GeneratePlanDetailedSchema>;
|
||||
export type CancelPlanInput = z.infer<typeof CancelPlanSchema>;
|
||||
export type PlanTaskUpdateInput = z.infer<typeof PlanTaskUpdateSchema>;
|
||||
export type PlanTaskAddInput = z.infer<typeof PlanTaskAddSchema>;
|
||||
export type CpuLimitInput = z.infer<typeof CpuLimitSchema>;
|
||||
export type SubagentWindowStatesInput = z.infer<typeof SubagentWindowStatesSchema>;
|
||||
export type SubagentParentMapInput = z.infer<typeof SubagentParentMapSchema>;
|
||||
export type InteractiveRespawnInput = z.infer<typeof InteractiveRespawnSchema>;
|
||||
export type RespawnEnableInput = z.infer<typeof RespawnEnableSchema>;
|
||||
export type PushSubscribeInput = z.infer<typeof PushSubscribeSchema>;
|
||||
export type PushPreferencesUpdateInput = z.infer<typeof PushPreferencesUpdateSchema>;
|
||||
export type RalphLoopStartInput = z.infer<typeof RalphLoopStartSchema>;
|
||||
```
|
||||
|
||||
### What NOT to do
|
||||
|
||||
Do NOT replace the `RespawnConfig` interface in `types.ts` with `z.infer<typeof RespawnConfigSchema>`. The schema has all optional fields (for partial config updates), but the interface has required fields (for the full config object). These are intentionally different shapes.
|
||||
|
||||
Similarly, do NOT try to unify every interface in `types.ts` with a schema -- most interfaces in `types.ts` represent internal domain objects (SessionState, TaskState, etc.) that have no corresponding Zod schema. The schemas only exist for API request validation.
|
||||
|
||||
### Future opportunity
|
||||
|
||||
In a future phase, route handlers in `server.ts` can use these inferred types for request body typing:
|
||||
```typescript
|
||||
const body = CreateSessionSchema.parse(request.body) as CreateSessionInput;
|
||||
```
|
||||
This task only adds the type exports. Migrating route handlers to use them is out of scope.
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
tsc --noEmit
|
||||
npm run lint
|
||||
npm run format:check
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 5: Fix Weak `not.toThrow()` Tests with Behavioral Assertions
|
||||
|
||||
**Files**:
|
||||
- `test/task-tracker.test.ts` -- 6 instances
|
||||
- `test/image-watcher.test.ts` -- 1 instance
|
||||
- `test/task-queue.test.ts` -- 1 instance
|
||||
- `test/hooks-config.test.ts` -- 1 instance
|
||||
- `test/session-manager.test.ts` -- 1 instance
|
||||
|
||||
**Time**: ~1 hour
|
||||
|
||||
### Problem
|
||||
|
||||
10 tests only assert `not.toThrow()` without verifying the actual defensive behavior. These tests prove the code doesn't crash but don't verify it does the right thing.
|
||||
|
||||
### Fix Strategy
|
||||
|
||||
After each `not.toThrow()`, add a behavioral assertion that verifies the state is correct (e.g., no tasks were created, no side effects occurred).
|
||||
|
||||
### Edit 1: `task-tracker.test.ts` -- null message (line 566)
|
||||
|
||||
**File**: `test/task-tracker.test.ts`
|
||||
|
||||
**Old code**:
|
||||
```typescript
|
||||
it('should handle null message', () => {
|
||||
expect(() => tracker.processMessage(null)).not.toThrow();
|
||||
});
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
it('should handle null message', () => {
|
||||
expect(() => tracker.processMessage(null)).not.toThrow();
|
||||
expect(tracker.getAllTasks().size).toBe(0);
|
||||
expect(tracker.getRunningCount()).toBe(0);
|
||||
});
|
||||
```
|
||||
|
||||
### Edit 2: `task-tracker.test.ts` -- message without content (line 569-571)
|
||||
|
||||
**File**: `test/task-tracker.test.ts`
|
||||
|
||||
**Old code**:
|
||||
```typescript
|
||||
it('should handle message without content', () => {
|
||||
expect(() => tracker.processMessage({ message: {} })).not.toThrow();
|
||||
});
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
it('should handle message without content', () => {
|
||||
expect(() => tracker.processMessage({ message: {} })).not.toThrow();
|
||||
expect(tracker.getAllTasks().size).toBe(0);
|
||||
});
|
||||
```
|
||||
|
||||
### Edit 3: `task-tracker.test.ts` -- empty content array (line 573-575)
|
||||
|
||||
**File**: `test/task-tracker.test.ts`
|
||||
|
||||
**Old code**:
|
||||
```typescript
|
||||
it('should handle empty content array', () => {
|
||||
expect(() => tracker.processMessage({ message: { content: [] } })).not.toThrow();
|
||||
});
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
it('should handle empty content array', () => {
|
||||
expect(() => tracker.processMessage({ message: { content: [] } })).not.toThrow();
|
||||
expect(tracker.getAllTasks().size).toBe(0);
|
||||
});
|
||||
```
|
||||
|
||||
### Edit 4: `task-tracker.test.ts` -- tool_result for unknown task (lines 577-590)
|
||||
|
||||
**File**: `test/task-tracker.test.ts`
|
||||
|
||||
**Old code**:
|
||||
```typescript
|
||||
it('should handle tool_result for unknown task', () => {
|
||||
expect(() => {
|
||||
tracker.processMessage({
|
||||
message: {
|
||||
content: [{
|
||||
type: 'tool_result',
|
||||
tool_use_id: 'unknown-task',
|
||||
is_error: false,
|
||||
content: 'Done',
|
||||
}],
|
||||
},
|
||||
});
|
||||
}).not.toThrow();
|
||||
});
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
it('should handle tool_result for unknown task', () => {
|
||||
expect(() => {
|
||||
tracker.processMessage({
|
||||
message: {
|
||||
content: [{
|
||||
type: 'tool_result',
|
||||
tool_use_id: 'unknown-task',
|
||||
is_error: false,
|
||||
content: 'Done',
|
||||
}],
|
||||
},
|
||||
});
|
||||
}).not.toThrow();
|
||||
expect(tracker.getTask('unknown-task')).toBeUndefined();
|
||||
expect(tracker.getAllTasks().size).toBe(0);
|
||||
});
|
||||
```
|
||||
|
||||
### Edit 5: `task-tracker.test.ts` -- empty terminal output (lines 592-595)
|
||||
|
||||
**File**: `test/task-tracker.test.ts`
|
||||
|
||||
**Old code**:
|
||||
```typescript
|
||||
it('should handle empty terminal output', () => {
|
||||
expect(() => tracker.processTerminalOutput('')).not.toThrow();
|
||||
expect(() => tracker.processTerminalOutput(' ')).not.toThrow();
|
||||
});
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
it('should handle empty terminal output', () => {
|
||||
expect(() => tracker.processTerminalOutput('')).not.toThrow();
|
||||
expect(() => tracker.processTerminalOutput(' ')).not.toThrow();
|
||||
expect(tracker.getAllTasks().size).toBe(0);
|
||||
expect(tracker.getRunningCount()).toBe(0);
|
||||
});
|
||||
```
|
||||
|
||||
### Edit 6: `image-watcher.test.ts` -- unwatchSession for non-watched session (line 123)
|
||||
|
||||
**File**: `test/image-watcher.test.ts`
|
||||
|
||||
**Old code**:
|
||||
```typescript
|
||||
it('should be safe to call for non-watched session', () => {
|
||||
expect(() => watcher.unwatchSession('nonexistent')).not.toThrow();
|
||||
});
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
it('should be safe to call for non-watched session', () => {
|
||||
expect(() => watcher.unwatchSession('nonexistent')).not.toThrow();
|
||||
expect(watcher.getWatchedSessions()).toHaveLength(0);
|
||||
});
|
||||
```
|
||||
|
||||
### Edit 7: `task-queue.test.ts` -- dependencies on non-existent tasks (lines 538-542)
|
||||
|
||||
**File**: `test/task-queue.test.ts`
|
||||
|
||||
**Old code**:
|
||||
```typescript
|
||||
it('should allow dependencies on non-existent tasks (just unsatisfied, not a cycle)', () => {
|
||||
// Dependencies on non-existent tasks are valid - they just won't be satisfied
|
||||
expect(() => {
|
||||
queue.addTask({ prompt: 'Task D', dependencies: ['non-existent-id'] });
|
||||
}).not.toThrow();
|
||||
});
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
it('should allow dependencies on non-existent tasks (just unsatisfied, not a cycle)', () => {
|
||||
// Dependencies on non-existent tasks are valid - they just won't be satisfied
|
||||
let task: ReturnType<typeof queue.addTask> | undefined;
|
||||
expect(() => {
|
||||
task = queue.addTask({ prompt: 'Task D', dependencies: ['non-existent-id'] });
|
||||
}).not.toThrow();
|
||||
expect(task).toBeDefined();
|
||||
expect(task!.dependencies).toEqual(['non-existent-id']);
|
||||
// Task should be pending but blocked (dependency unsatisfied)
|
||||
expect(queue.next()?.prompt).toBeUndefined();
|
||||
});
|
||||
```
|
||||
|
||||
Wait -- `queue.next()` returns `null` when no next task is available (all blocked). Let me adjust:
|
||||
|
||||
**New code** (corrected):
|
||||
```typescript
|
||||
it('should allow dependencies on non-existent tasks (just unsatisfied, not a cycle)', () => {
|
||||
// Dependencies on non-existent tasks are valid - they just won't be satisfied
|
||||
let task: ReturnType<typeof queue.addTask> | undefined;
|
||||
expect(() => {
|
||||
task = queue.addTask({ prompt: 'Task D', dependencies: ['non-existent-id'] });
|
||||
}).not.toThrow();
|
||||
expect(task).toBeDefined();
|
||||
expect(task!.dependencies).toEqual(['non-existent-id']);
|
||||
// Task exists but is blocked (dependency unsatisfied), so next() skips it
|
||||
expect(queue.getAllTasks()).toHaveLength(1);
|
||||
expect(queue.next()).toBeNull();
|
||||
});
|
||||
```
|
||||
|
||||
### Edit 8: `hooks-config.test.ts` -- valid JSON check (line 129)
|
||||
|
||||
**File**: `test/hooks-config.test.ts`
|
||||
|
||||
**Old code**:
|
||||
```typescript
|
||||
it('should write valid JSON', () => {
|
||||
writeHooksConfig(testDir);
|
||||
const settingsPath = join(testDir, '.claude', 'settings.local.json');
|
||||
const content = readFileSync(settingsPath, 'utf-8');
|
||||
expect(() => JSON.parse(content)).not.toThrow();
|
||||
});
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
it('should write valid JSON', () => {
|
||||
writeHooksConfig(testDir);
|
||||
const settingsPath = join(testDir, '.claude', 'settings.local.json');
|
||||
const content = readFileSync(settingsPath, 'utf-8');
|
||||
const parsed = JSON.parse(content);
|
||||
expect(parsed).toBeDefined();
|
||||
expect(typeof parsed).toBe('object');
|
||||
expect(parsed.hooks).toBeDefined();
|
||||
});
|
||||
```
|
||||
|
||||
### Edit 9: `session-manager.test.ts` -- stopSession for non-existent (line 216)
|
||||
|
||||
**File**: `test/session-manager.test.ts`
|
||||
|
||||
**Old code**:
|
||||
```typescript
|
||||
it('should handle non-existent session gracefully', async () => {
|
||||
await expect(manager.stopSession('non-existent')).resolves.not.toThrow();
|
||||
});
|
||||
```
|
||||
|
||||
**New code**:
|
||||
```typescript
|
||||
it('should handle non-existent session gracefully', async () => {
|
||||
await expect(manager.stopSession('non-existent')).resolves.not.toThrow();
|
||||
expect(manager.getSessionCount()).toBe(0);
|
||||
});
|
||||
```
|
||||
|
||||
### Verification
|
||||
|
||||
Run each test file individually:
|
||||
|
||||
```bash
|
||||
npx vitest run test/task-tracker.test.ts
|
||||
npx vitest run test/image-watcher.test.ts
|
||||
npx vitest run test/task-queue.test.ts
|
||||
npx vitest run test/hooks-config.test.ts
|
||||
npx vitest run test/session-manager.test.ts
|
||||
```
|
||||
|
||||
**Important**: `hooks-config.test.ts` and `session-manager.test.ts` spawn real servers on ports 3130-3131. Only run them if you are NOT running other tests that use those ports.
|
||||
|
||||
---
|
||||
|
||||
## Final Verification Checklist
|
||||
|
||||
After all 5 tasks are complete, run the following in order:
|
||||
|
||||
```bash
|
||||
# 1. TypeScript type checking
|
||||
tsc --noEmit
|
||||
|
||||
# 2. Linting
|
||||
npm run lint
|
||||
|
||||
# 3. Formatting
|
||||
npm run format:check
|
||||
|
||||
# 4. Run affected test files individually (NOT the full suite)
|
||||
npx vitest run test/string-utilities.test.ts
|
||||
npx vitest run test/task-tracker.test.ts
|
||||
npx vitest run test/image-watcher.test.ts
|
||||
npx vitest run test/task-queue.test.ts
|
||||
npx vitest run test/session-manager.test.ts
|
||||
npx vitest run test/hooks-config.test.ts
|
||||
```
|
||||
|
||||
If any formatting issues arise, fix with:
|
||||
```bash
|
||||
npm run format
|
||||
```
|
||||
|
||||
If any lint issues arise, fix with:
|
||||
```bash
|
||||
npm run lint:fix
|
||||
```
|
||||
|
||||
### Summary of Changes
|
||||
|
||||
| Task | Files Modified | Files Created |
|
||||
|------|---------------|---------------|
|
||||
| 1. Barrel exports | `src/utils/index.ts` | -- |
|
||||
| 2. Dead functions | `src/utils/string-similarity.ts` | -- |
|
||||
| 3. EXEC_TIMEOUT_MS | `src/utils/claude-cli-resolver.ts`, `src/utils/opencode-cli-resolver.ts`, `src/tmux-manager.ts` | `src/config/exec-timeout.ts` |
|
||||
| 4. z.infer types | `src/web/schemas.ts` | -- |
|
||||
| 5. Weak tests | `test/task-tracker.test.ts`, `test/image-watcher.test.ts`, `test/task-queue.test.ts`, `test/hooks-config.test.ts`, `test/session-manager.test.ts` | -- |
|
||||
|
||||
**Total files modified**: 10
|
||||
**Total files created**: 1
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
+35
-40
@@ -15,6 +15,7 @@
|
||||
import { EventEmitter } from 'node:events';
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
import { ActiveBashTool } from './types.js';
|
||||
import { CleanupManager, Debouncer } from './utils/index.js';
|
||||
|
||||
// ========== Configuration Constants ==========
|
||||
|
||||
@@ -145,15 +146,14 @@ export class BashToolParser extends EventEmitter<BashToolParserEvents> {
|
||||
private _workingDir: string;
|
||||
private _homeDir: string;
|
||||
|
||||
// Track auto-remove timers for cleanup
|
||||
private _autoRemoveTimers: Set<ReturnType<typeof setTimeout>> = new Set();
|
||||
// Centralized resource cleanup for auto-remove timers
|
||||
private cleanup = new CleanupManager();
|
||||
|
||||
// Flag to prevent operations after destroy
|
||||
private _destroyed: boolean = false;
|
||||
|
||||
// Debouncing
|
||||
private _pendingUpdate: boolean = false;
|
||||
private _updateTimer: ReturnType<typeof setTimeout> | null = null;
|
||||
private _updateDeb = new Debouncer(EVENT_DEBOUNCE_MS);
|
||||
|
||||
constructor(config: BashToolParserConfig) {
|
||||
super();
|
||||
@@ -524,13 +524,15 @@ export class BashToolParser extends EventEmitter<BashToolParserEvents> {
|
||||
this.scheduleUpdate();
|
||||
|
||||
// Remove completed tool after a short delay to allow UI to show completion
|
||||
const timer = setTimeout(() => {
|
||||
this._autoRemoveTimers.delete(timer);
|
||||
if (this._destroyed) return;
|
||||
this._activeTools.delete(tool.id);
|
||||
this.scheduleUpdate();
|
||||
}, 2000);
|
||||
this._autoRemoveTimers.add(timer);
|
||||
this.cleanup.setTimeout(
|
||||
() => {
|
||||
if (this._destroyed) return;
|
||||
this._activeTools.delete(tool.id);
|
||||
this.scheduleUpdate();
|
||||
},
|
||||
2000,
|
||||
{ description: 'auto-remove completed tool' }
|
||||
);
|
||||
}
|
||||
this._lastToolId = null;
|
||||
return;
|
||||
@@ -562,13 +564,15 @@ export class BashToolParser extends EventEmitter<BashToolParserEvents> {
|
||||
this.scheduleUpdate();
|
||||
|
||||
// Auto-remove suggestions after 30 seconds
|
||||
const timer = setTimeout(() => {
|
||||
this._autoRemoveTimers.delete(timer);
|
||||
if (this._destroyed) return;
|
||||
this._activeTools.delete(tool.id);
|
||||
this.scheduleUpdate();
|
||||
}, 30000);
|
||||
this._autoRemoveTimers.add(timer);
|
||||
this.cleanup.setTimeout(
|
||||
() => {
|
||||
if (this._destroyed) return;
|
||||
this._activeTools.delete(tool.id);
|
||||
this.scheduleUpdate();
|
||||
},
|
||||
30000,
|
||||
{ description: 'auto-remove suggestion tool' }
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -599,13 +603,15 @@ export class BashToolParser extends EventEmitter<BashToolParserEvents> {
|
||||
this.scheduleUpdate();
|
||||
|
||||
// Auto-remove after 60 seconds
|
||||
const timer = setTimeout(() => {
|
||||
this._autoRemoveTimers.delete(timer);
|
||||
if (this._destroyed) return;
|
||||
this._activeTools.delete(tool.id);
|
||||
this.scheduleUpdate();
|
||||
}, 60000);
|
||||
this._autoRemoveTimers.add(timer);
|
||||
this.cleanup.setTimeout(
|
||||
() => {
|
||||
if (this._destroyed) return;
|
||||
this._activeTools.delete(tool.id);
|
||||
this.scheduleUpdate();
|
||||
},
|
||||
60000,
|
||||
{ description: 'auto-remove log file tool' }
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -675,13 +681,9 @@ export class BashToolParser extends EventEmitter<BashToolParserEvents> {
|
||||
* Schedule a debounced update emission.
|
||||
*/
|
||||
private scheduleUpdate(): void {
|
||||
if (this._pendingUpdate) return;
|
||||
|
||||
this._pendingUpdate = true;
|
||||
this._updateTimer = setTimeout(() => {
|
||||
this._pendingUpdate = false;
|
||||
this._updateDeb.schedule(() => {
|
||||
this.emitUpdate();
|
||||
}, EVENT_DEBOUNCE_MS);
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -696,15 +698,8 @@ export class BashToolParser extends EventEmitter<BashToolParserEvents> {
|
||||
*/
|
||||
destroy(): void {
|
||||
this._destroyed = true;
|
||||
if (this._updateTimer) {
|
||||
clearTimeout(this._updateTimer);
|
||||
this._updateTimer = null;
|
||||
}
|
||||
// Clear all auto-remove timers to prevent orphaned callbacks
|
||||
for (const timer of this._autoRemoveTimers) {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
this._autoRemoveTimers.clear();
|
||||
this._updateDeb.dispose();
|
||||
this.cleanup.dispose();
|
||||
this._activeTools.clear();
|
||||
this.removeAllListeners();
|
||||
}
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
/**
|
||||
* @fileoverview Shared exec timeout constant.
|
||||
*
|
||||
* Used by CLI resolvers and tmux-manager for execSync/exec calls.
|
||||
*
|
||||
* @module config/exec-timeout
|
||||
*/
|
||||
|
||||
/** Timeout for exec commands (5 seconds) */
|
||||
export const EXEC_TIMEOUT_MS = 5000;
|
||||
+17
-31
@@ -13,6 +13,7 @@ import { watch, type FSWatcher } from 'chokidar';
|
||||
import { basename, extname, relative } from 'node:path';
|
||||
import { statSync } from 'node:fs';
|
||||
import type { ImageDetectedEvent } from './types.js';
|
||||
import { KeyedDebouncer } from './utils/index.js';
|
||||
|
||||
// ========== Types ==========
|
||||
|
||||
@@ -65,11 +66,11 @@ export class ImageWatcher extends EventEmitter {
|
||||
/** Map of sessionId -> working directory path */
|
||||
private sessionDirs = new Map<string, string>();
|
||||
|
||||
/** Debounce timers for rapid image creation (keyed by filePath) */
|
||||
private debounceTimers = new Map<string, NodeJS.Timeout>();
|
||||
/** Per-file debouncer for rapid image creation */
|
||||
private fileDeb = new KeyedDebouncer(DEBOUNCE_DELAY_MS);
|
||||
|
||||
/** Track which session owns each debounce timer (for cleanup) */
|
||||
private timerToSession = new Map<string, string>();
|
||||
/** Track which session owns each debounced file (for cleanup) */
|
||||
private fileToSession = new Map<string, string>();
|
||||
|
||||
/** Per-session burst tracking: sessionId -> { count, windowStart } */
|
||||
private burstTrackers = new Map<string, { count: number; windowStart: number }>();
|
||||
@@ -118,11 +119,8 @@ export class ImageWatcher extends EventEmitter {
|
||||
this.sessionDirs.clear();
|
||||
|
||||
// Clear all debounce timers
|
||||
for (const timer of this.debounceTimers.values()) {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
this.debounceTimers.clear();
|
||||
this.timerToSession.clear();
|
||||
this.fileDeb.dispose();
|
||||
this.fileToSession.clear();
|
||||
this.burstTrackers.clear();
|
||||
}
|
||||
|
||||
@@ -212,20 +210,15 @@ export class ImageWatcher extends EventEmitter {
|
||||
this.sessionDirs.delete(sessionId);
|
||||
|
||||
// Clear any pending debounce timers for this session
|
||||
// Collect keys first to avoid iterator invalidation during deletion
|
||||
const toDelete: string[] = [];
|
||||
for (const [filePath, ownerId] of this.timerToSession) {
|
||||
const toCancel: string[] = [];
|
||||
for (const [filePath, ownerId] of this.fileToSession) {
|
||||
if (ownerId === sessionId) {
|
||||
toDelete.push(filePath);
|
||||
toCancel.push(filePath);
|
||||
}
|
||||
}
|
||||
for (const filePath of toDelete) {
|
||||
const timer = this.debounceTimers.get(filePath);
|
||||
if (timer) {
|
||||
clearTimeout(timer);
|
||||
this.debounceTimers.delete(filePath);
|
||||
}
|
||||
this.timerToSession.delete(filePath);
|
||||
for (const filePath of toCancel) {
|
||||
this.fileDeb.cancelKey(filePath);
|
||||
this.fileToSession.delete(filePath);
|
||||
}
|
||||
this.burstTrackers.delete(sessionId);
|
||||
}
|
||||
@@ -269,22 +262,15 @@ export class ImageWatcher extends EventEmitter {
|
||||
}
|
||||
|
||||
// Debounce rapid file creation (e.g., multiple screenshots quickly)
|
||||
const existingTimer = this.debounceTimers.get(filePath);
|
||||
if (existingTimer) {
|
||||
clearTimeout(existingTimer);
|
||||
}
|
||||
|
||||
const timer = setTimeout(() => {
|
||||
this.debounceTimers.delete(filePath);
|
||||
this.timerToSession.delete(filePath);
|
||||
this.fileDeb.schedule(filePath, () => {
|
||||
this.fileToSession.delete(filePath);
|
||||
this.emitImageDetected(sessionId, filePath);
|
||||
// Increment burst count on actual emission (not on detection)
|
||||
const b = this.burstTrackers.get(sessionId);
|
||||
if (b) b.count++;
|
||||
}, DEBOUNCE_DELAY_MS);
|
||||
});
|
||||
|
||||
this.debounceTimers.set(filePath, timer);
|
||||
this.timerToSession.set(filePath, sessionId);
|
||||
this.fileToSession.set(filePath, sessionId);
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
+4
-11
@@ -11,6 +11,7 @@ import { join } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
import webpush from 'web-push';
|
||||
import type { VapidKeys, PushSubscriptionRecord } from './types.js';
|
||||
import { Debouncer } from './utils/index.js';
|
||||
|
||||
const DATA_DIR = join(homedir(), '.codeman');
|
||||
const KEYS_FILE = join(DATA_DIR, 'push-keys.json');
|
||||
@@ -20,7 +21,7 @@ const SAVE_DEBOUNCE_MS = 500;
|
||||
export class PushSubscriptionStore {
|
||||
private vapidKeys: VapidKeys | null = null;
|
||||
private subscriptions: Map<string, PushSubscriptionRecord> = new Map();
|
||||
private saveTimer: NodeJS.Timeout | null = null;
|
||||
private saveDeb = new Debouncer(SAVE_DEBOUNCE_MS);
|
||||
private _disposed = false;
|
||||
|
||||
constructor() {
|
||||
@@ -149,10 +150,7 @@ export class PushSubscriptionStore {
|
||||
/** Schedule a debounced save */
|
||||
private scheduleSave(): void {
|
||||
if (this._disposed) return;
|
||||
if (this.saveTimer) clearTimeout(this.saveTimer);
|
||||
this.saveTimer = setTimeout(() => {
|
||||
this.flushSave();
|
||||
}, SAVE_DEBOUNCE_MS);
|
||||
this.saveDeb.schedule(() => this.flushSave());
|
||||
}
|
||||
|
||||
/** Immediately persist subscriptions to disk */
|
||||
@@ -169,11 +167,6 @@ export class PushSubscriptionStore {
|
||||
dispose(): void {
|
||||
if (this._disposed) return;
|
||||
this._disposed = true;
|
||||
if (this.saveTimer) {
|
||||
clearTimeout(this.saveTimer);
|
||||
this.saveTimer = null;
|
||||
}
|
||||
// Final flush
|
||||
this.flushSave();
|
||||
this.saveDeb.flush(() => this.flushSave());
|
||||
}
|
||||
}
|
||||
|
||||
+45
-82
@@ -34,7 +34,14 @@ import {
|
||||
PlanTaskStatus,
|
||||
TddPhase,
|
||||
} from './types.js';
|
||||
import { ANSI_ESCAPE_PATTERN_SIMPLE, fuzzyPhraseMatch, todoContentHash, stringSimilarity } from './utils/index.js';
|
||||
import {
|
||||
ANSI_ESCAPE_PATTERN_SIMPLE,
|
||||
CleanupManager,
|
||||
Debouncer,
|
||||
fuzzyPhraseMatch,
|
||||
todoContentHash,
|
||||
stringSimilarity,
|
||||
} from './utils/index.js';
|
||||
import { MAX_LINE_BUFFER_SIZE } from './config/buffer-limits.js';
|
||||
import { MAX_TODOS_PER_SESSION } from './config/map-limits.js';
|
||||
|
||||
@@ -559,17 +566,14 @@ export class RalphTracker extends EventEmitter {
|
||||
/** Timestamp of last cleanup check for throttling */
|
||||
private _lastCleanupTime: number = 0;
|
||||
|
||||
/** Debounce timer for todoUpdate events */
|
||||
private _todoUpdateTimer: NodeJS.Timeout | null = null;
|
||||
/** Centralized resource cleanup for timers/intervals */
|
||||
private cleanup = new CleanupManager();
|
||||
|
||||
/** Debounce timer for loopUpdate events */
|
||||
private _loopUpdateTimer: NodeJS.Timeout | null = null;
|
||||
/** Debouncer for todoUpdate events */
|
||||
private _todoUpdateDeb = new Debouncer(EVENT_DEBOUNCE_MS);
|
||||
|
||||
/** Flag indicating pending todoUpdate emission */
|
||||
private _todoUpdatePending: boolean = false;
|
||||
|
||||
/** Flag indicating pending loopUpdate emission */
|
||||
private _loopUpdatePending: boolean = false;
|
||||
/** Debouncer for loopUpdate events */
|
||||
private _loopUpdateDeb = new Debouncer(EVENT_DEBOUNCE_MS);
|
||||
|
||||
/** When true, prevents auto-enable on pattern detection */
|
||||
private _autoEnableDisabled: boolean = true;
|
||||
@@ -621,8 +625,8 @@ export class RalphTracker extends EventEmitter {
|
||||
/** Error handler for FSWatcher (stored for cleanup to prevent memory leak) */
|
||||
private _fixPlanWatcherErrorHandler: ((err: Error) => void) | null = null;
|
||||
|
||||
/** Debounce timer for file change events */
|
||||
private _fixPlanReloadTimer: NodeJS.Timeout | null = null;
|
||||
/** Debouncer for file change events */
|
||||
private _fixPlanReloadDeb = new Debouncer(500);
|
||||
|
||||
/** Path to the @fix_plan.md file being watched */
|
||||
private _fixPlanPath: string | null = null;
|
||||
@@ -665,8 +669,8 @@ export class RalphTracker extends EventEmitter {
|
||||
/** Last observed iteration count for stall detection */
|
||||
private _lastObservedIteration: number = 0;
|
||||
|
||||
/** Timer for iteration stall detection */
|
||||
private _iterationStallTimer: NodeJS.Timeout | null = null;
|
||||
/** CleanupManager registration ID for iteration stall detection interval */
|
||||
private _iterationStallTimerId: string | null = null;
|
||||
|
||||
/** Iteration stall warning threshold (ms) - default 10 minutes */
|
||||
private _iterationStallWarningMs: number = 10 * 60 * 1000;
|
||||
@@ -869,14 +873,9 @@ export class RalphTracker extends EventEmitter {
|
||||
*/
|
||||
private handleFixPlanChange(): void {
|
||||
// Debounce rapid changes (e.g., multiple writes)
|
||||
if (this._fixPlanReloadTimer) {
|
||||
clearTimeout(this._fixPlanReloadTimer);
|
||||
}
|
||||
|
||||
this._fixPlanReloadTimer = setTimeout(() => {
|
||||
this._fixPlanReloadTimer = null;
|
||||
this._fixPlanReloadDeb.schedule(() => {
|
||||
this.loadFixPlanFromDisk();
|
||||
}, 500); // 500ms debounce
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -892,10 +891,7 @@ export class RalphTracker extends EventEmitter {
|
||||
this._fixPlanWatcher.close();
|
||||
this._fixPlanWatcher = null;
|
||||
}
|
||||
if (this._fixPlanReloadTimer) {
|
||||
clearTimeout(this._fixPlanReloadTimer);
|
||||
this._fixPlanReloadTimer = null;
|
||||
}
|
||||
this._fixPlanReloadDeb.cancel();
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1023,16 +1019,8 @@ export class RalphTracker extends EventEmitter {
|
||||
* Called during reset/fullReset to prevent stale emissions.
|
||||
*/
|
||||
private clearDebounceTimers(): void {
|
||||
if (this._todoUpdateTimer) {
|
||||
clearTimeout(this._todoUpdateTimer);
|
||||
this._todoUpdateTimer = null;
|
||||
}
|
||||
if (this._loopUpdateTimer) {
|
||||
clearTimeout(this._loopUpdateTimer);
|
||||
this._loopUpdateTimer = null;
|
||||
}
|
||||
this._todoUpdatePending = false;
|
||||
this._loopUpdatePending = false;
|
||||
this._todoUpdateDeb.cancel();
|
||||
this._loopUpdateDeb.cancel();
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1041,19 +1029,9 @@ export class RalphTracker extends EventEmitter {
|
||||
* The event fires after EVENT_DEBOUNCE_MS of inactivity.
|
||||
*/
|
||||
private emitTodoUpdateDebounced(): void {
|
||||
this._todoUpdatePending = true;
|
||||
|
||||
if (this._todoUpdateTimer) {
|
||||
clearTimeout(this._todoUpdateTimer);
|
||||
}
|
||||
|
||||
this._todoUpdateTimer = setTimeout(() => {
|
||||
if (this._todoUpdatePending) {
|
||||
this._todoUpdatePending = false;
|
||||
this._todoUpdateTimer = null;
|
||||
this.emit('todoUpdate', this.todos);
|
||||
}
|
||||
}, EVENT_DEBOUNCE_MS);
|
||||
this._todoUpdateDeb.schedule(() => {
|
||||
this.emit('todoUpdate', this.todos);
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1062,19 +1040,9 @@ export class RalphTracker extends EventEmitter {
|
||||
* The event fires after EVENT_DEBOUNCE_MS of inactivity.
|
||||
*/
|
||||
private emitLoopUpdateDebounced(): void {
|
||||
this._loopUpdatePending = true;
|
||||
|
||||
if (this._loopUpdateTimer) {
|
||||
clearTimeout(this._loopUpdateTimer);
|
||||
}
|
||||
|
||||
this._loopUpdateTimer = setTimeout(() => {
|
||||
if (this._loopUpdatePending) {
|
||||
this._loopUpdatePending = false;
|
||||
this._loopUpdateTimer = null;
|
||||
this.emit('loopUpdate', this.loopState);
|
||||
}
|
||||
}, EVENT_DEBOUNCE_MS);
|
||||
this._loopUpdateDeb.schedule(() => {
|
||||
this.emit('loopUpdate', this.loopState);
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1082,21 +1050,11 @@ export class RalphTracker extends EventEmitter {
|
||||
* Useful for testing or when immediate state sync is needed.
|
||||
*/
|
||||
flushPendingEvents(): void {
|
||||
if (this._todoUpdatePending) {
|
||||
this._todoUpdatePending = false;
|
||||
if (this._todoUpdateTimer) {
|
||||
clearTimeout(this._todoUpdateTimer);
|
||||
this._todoUpdateTimer = null;
|
||||
}
|
||||
this.emit('todoUpdate', this.todos);
|
||||
if (this._todoUpdateDeb.isPending) {
|
||||
this._todoUpdateDeb.flush(() => this.emit('todoUpdate', this.todos));
|
||||
}
|
||||
if (this._loopUpdatePending) {
|
||||
this._loopUpdatePending = false;
|
||||
if (this._loopUpdateTimer) {
|
||||
clearTimeout(this._loopUpdateTimer);
|
||||
this._loopUpdateTimer = null;
|
||||
}
|
||||
this.emit('loopUpdate', this.loopState);
|
||||
if (this._loopUpdateDeb.isPending) {
|
||||
this._loopUpdateDeb.flush(() => this.emit('loopUpdate', this.loopState));
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1116,18 +1074,22 @@ export class RalphTracker extends EventEmitter {
|
||||
this._iterationStallWarned = false;
|
||||
|
||||
// Check every minute
|
||||
this._iterationStallTimer = setInterval(() => {
|
||||
this.checkIterationStall();
|
||||
}, 60 * 1000);
|
||||
this._iterationStallTimerId = this.cleanup.setInterval(
|
||||
() => {
|
||||
this.checkIterationStall();
|
||||
},
|
||||
60 * 1000,
|
||||
{ description: 'iteration stall detection' }
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop iteration stall detection timer.
|
||||
*/
|
||||
stopIterationStallDetection(): void {
|
||||
if (this._iterationStallTimer) {
|
||||
clearInterval(this._iterationStallTimer);
|
||||
this._iterationStallTimer = null;
|
||||
if (this._iterationStallTimerId) {
|
||||
this.cleanup.unregister(this._iterationStallTimerId);
|
||||
this._iterationStallTimerId = null;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -3888,7 +3850,8 @@ export class RalphTracker extends EventEmitter {
|
||||
destroy(): void {
|
||||
this.clearDebounceTimers();
|
||||
this.stopWatchingFixPlan();
|
||||
this.stopIterationStallDetection();
|
||||
this._fixPlanReloadDeb.dispose();
|
||||
this.cleanup.dispose();
|
||||
this._todos.clear();
|
||||
this._taskNumberToContent.clear();
|
||||
this._todoStartTimes.clear();
|
||||
|
||||
+153
-164
@@ -41,7 +41,7 @@ import { AiIdleChecker, type AiCheckResult, type AiCheckState } from './ai-idle-
|
||||
import { AiPlanChecker, type AiPlanCheckResult } from './ai-plan-checker.js';
|
||||
import type { TeamWatcher } from './team-watcher.js';
|
||||
import { BufferAccumulator } from './utils/buffer-accumulator.js';
|
||||
import { ANSI_ESCAPE_PATTERN_SIMPLE, TOKEN_PATTERN, assertNever } from './utils/index.js';
|
||||
import { ANSI_ESCAPE_PATTERN_SIMPLE, TOKEN_PATTERN, assertNever, CleanupManager } from './utils/index.js';
|
||||
import { MAX_RESPAWN_BUFFER_SIZE, TRIM_RESPAWN_BUFFER_TO as RESPAWN_BUFFER_TRIM_SIZE } from './config/buffer-limits.js';
|
||||
import type {
|
||||
RespawnCycleMetrics,
|
||||
@@ -641,26 +641,29 @@ export class RespawnController extends EventEmitter {
|
||||
/** Current state machine state */
|
||||
private _state: RespawnState = 'stopped';
|
||||
|
||||
/** Timer for step delays */
|
||||
private stepTimer: NodeJS.Timeout | null = null;
|
||||
/** Centralized resource cleanup manager for timers */
|
||||
private cleanup = new CleanupManager();
|
||||
|
||||
/** Timer for completion confirmation (Layer 2) */
|
||||
private completionConfirmTimer: NodeJS.Timeout | null = null;
|
||||
/** Timer ID for step delays */
|
||||
private stepTimerId: string | null = null;
|
||||
|
||||
/** Timer for no-output fallback (Layer 5) */
|
||||
private noOutputTimer: NodeJS.Timeout | null = null;
|
||||
/** Timer ID for completion confirmation (Layer 2) */
|
||||
private completionConfirmTimerId: string | null = null;
|
||||
|
||||
/** Timer for periodic detection status updates */
|
||||
private detectionUpdateTimer: NodeJS.Timeout | null = null;
|
||||
/** Timer ID for no-output fallback (Layer 5) */
|
||||
private noOutputTimerId: string | null = null;
|
||||
|
||||
/** Timer ID for periodic detection status updates */
|
||||
private detectionUpdateTimerId: string | null = null;
|
||||
|
||||
/** Cached key fields from last emitted detection status (for dedup) */
|
||||
private lastEmittedDetectionKey: string = '';
|
||||
|
||||
/** Timer for auto-accepting plan mode prompts */
|
||||
private autoAcceptTimer: NodeJS.Timeout | null = null;
|
||||
/** Timer ID for auto-accepting plan mode prompts */
|
||||
private autoAcceptTimerId: string | null = null;
|
||||
|
||||
/** Timer for pre-filter silence detection (triggers AI check) */
|
||||
private preFilterTimer: NodeJS.Timeout | null = null;
|
||||
/** Timer ID for pre-filter silence detection (triggers AI check) */
|
||||
private preFilterTimerId: string | null = null;
|
||||
|
||||
/** Whether any terminal output has been received since start/last-auto-accept */
|
||||
private hasReceivedOutput: boolean = false;
|
||||
@@ -682,8 +685,8 @@ export class RespawnController extends EventEmitter {
|
||||
/** Timestamp when idle_prompt was received */
|
||||
private idlePromptTime: number | null = null;
|
||||
|
||||
/** Timer for short confirmation after hook signal (handles race conditions) */
|
||||
private hookConfirmTimer: NodeJS.Timeout | null = null;
|
||||
/** Timer ID for short confirmation after hook signal (handles race conditions) */
|
||||
private hookConfirmTimerId: string | null = null;
|
||||
|
||||
/** Confirmation delay after hook signal before confirming idle (ms) */
|
||||
private static readonly HOOK_CONFIRM_DELAY_MS = 3000;
|
||||
@@ -718,11 +721,11 @@ export class RespawnController extends EventEmitter {
|
||||
/** Unique ID for current AI check request (to detect stale results) */
|
||||
private _currentAiCheckId: string | null = null;
|
||||
|
||||
/** Timer for /clear step fallback (sends /init if no prompt detected) */
|
||||
private clearFallbackTimer: NodeJS.Timeout | null = null;
|
||||
/** Timer ID for /clear step fallback (sends /init if no prompt detected) */
|
||||
private clearFallbackTimerId: string | null = null;
|
||||
|
||||
/** Timer for step completion confirmation (waits for silence after completion) */
|
||||
private stepConfirmTimer: NodeJS.Timeout | null = null;
|
||||
/** Timer ID for step completion confirmation (waits for silence after completion) */
|
||||
private stepConfirmTimerId: string | null = null;
|
||||
|
||||
/** Fallback timeout for /clear step (ms) - sends /init without waiting for prompt */
|
||||
private static readonly CLEAR_FALLBACK_TIMEOUT_MS = 10000;
|
||||
@@ -741,8 +744,8 @@ export class RespawnController extends EventEmitter {
|
||||
/** Timestamp when the current state was entered */
|
||||
private stateEnteredAt: number = 0;
|
||||
|
||||
/** Timer for stuck-state detection */
|
||||
private stuckStateTimer: NodeJS.Timeout | null = null;
|
||||
/** Timer ID for stuck-state detection */
|
||||
private stuckStateTimerId: string | null = null;
|
||||
|
||||
/** Whether a stuck-state warning has been emitted for current state */
|
||||
private stuckStateWarned: boolean = false;
|
||||
@@ -1200,31 +1203,35 @@ export class RespawnController extends EventEmitter {
|
||||
this.stopDetectionUpdates();
|
||||
if (this._state === 'stopped') return;
|
||||
this.lastEmittedDetectionKey = '';
|
||||
this.detectionUpdateTimer = setInterval(() => {
|
||||
try {
|
||||
if (this._state !== 'stopped') {
|
||||
const status = this.getDetectionStatus();
|
||||
// Only emit when status meaningfully changed (confidence, state text, or timer values)
|
||||
// to avoid broadcasting identical data every 2s for stable/idle sessions.
|
||||
const key = `${status.confidenceLevel}|${status.statusText}|${this._state}`;
|
||||
if (key !== this.lastEmittedDetectionKey) {
|
||||
this.lastEmittedDetectionKey = key;
|
||||
this.emit('detectionUpdate', status);
|
||||
this.detectionUpdateTimerId = this.cleanup.setInterval(
|
||||
() => {
|
||||
try {
|
||||
if (this._state !== 'stopped') {
|
||||
const status = this.getDetectionStatus();
|
||||
// Only emit when status meaningfully changed (confidence, state text, or timer values)
|
||||
// to avoid broadcasting identical data every 2s for stable/idle sessions.
|
||||
const key = `${status.confidenceLevel}|${status.statusText}|${this._state}`;
|
||||
if (key !== this.lastEmittedDetectionKey) {
|
||||
this.lastEmittedDetectionKey = key;
|
||||
this.emit('detectionUpdate', status);
|
||||
}
|
||||
}
|
||||
} catch (err) {
|
||||
console.error(`[RespawnController] Error in detectionUpdateTimer:`, err);
|
||||
}
|
||||
} catch (err) {
|
||||
console.error(`[RespawnController] Error in detectionUpdateTimer:`, err);
|
||||
}
|
||||
}, 2000);
|
||||
},
|
||||
2000,
|
||||
{ description: 'detection status updates' }
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop periodic detection status updates.
|
||||
*/
|
||||
private stopDetectionUpdates(): void {
|
||||
if (this.detectionUpdateTimer) {
|
||||
clearInterval(this.detectionUpdateTimer);
|
||||
this.detectionUpdateTimer = null;
|
||||
if (this.detectionUpdateTimerId) {
|
||||
this.cleanup.unregister(this.detectionUpdateTimerId);
|
||||
this.detectionUpdateTimerId = null;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1515,8 +1522,8 @@ export class RespawnController extends EventEmitter {
|
||||
this.lastWorkingPatternTime = now;
|
||||
|
||||
// Cancel hook confirmation timer if running
|
||||
this.cancelTrackedTimer('hook-confirm', this.hookConfirmTimer, 'working patterns detected');
|
||||
this.hookConfirmTimer = null;
|
||||
this.cancelTrackedTimer('hook-confirm', this.hookConfirmTimerId, 'working patterns detected');
|
||||
this.hookConfirmTimerId = null;
|
||||
|
||||
// Cancel any pending completion confirmation
|
||||
this.cancelCompletionConfirm();
|
||||
@@ -1650,8 +1657,8 @@ export class RespawnController extends EventEmitter {
|
||||
*/
|
||||
private checkClearComplete(): void {
|
||||
// Clear the fallback timer since we got prompt detection
|
||||
this.cancelTrackedTimer('clear-fallback', this.clearFallbackTimer, 'prompt detected');
|
||||
this.clearFallbackTimer = null;
|
||||
this.cancelTrackedTimer('clear-fallback', this.clearFallbackTimerId, 'prompt detected');
|
||||
this.clearFallbackTimerId = null;
|
||||
this.logAction('step', '/clear completed');
|
||||
this.emit('stepCompleted', 'clear');
|
||||
|
||||
@@ -1699,11 +1706,11 @@ export class RespawnController extends EventEmitter {
|
||||
this.logAction('step', 'Monitoring if /init triggered work...');
|
||||
|
||||
// Give Claude a moment to start working before checking for idle
|
||||
this.stepTimer = this.startTrackedTimer(
|
||||
this.stepTimerId = this.startTrackedTimer(
|
||||
'init-monitor',
|
||||
3000,
|
||||
() => {
|
||||
this.stepTimer = null;
|
||||
this.stepTimerId = null;
|
||||
// If still in monitoring state and no work detected, consider it idle
|
||||
if (this._state === 'monitoring_init' && !this.workingDetected) {
|
||||
this.checkMonitoringInitIdle();
|
||||
@@ -1719,9 +1726,9 @@ export class RespawnController extends EventEmitter {
|
||||
* @fires stepCompleted - With step 'init'
|
||||
*/
|
||||
private checkMonitoringInitIdle(): void {
|
||||
if (this.stepTimer) {
|
||||
clearTimeout(this.stepTimer);
|
||||
this.stepTimer = null;
|
||||
if (this.stepTimerId) {
|
||||
this.cleanup.unregister(this.stepTimerId);
|
||||
this.stepTimerId = null;
|
||||
}
|
||||
this.log('/init did not trigger work, sending kickstart prompt');
|
||||
this.emit('stepCompleted', 'init');
|
||||
@@ -1737,11 +1744,11 @@ export class RespawnController extends EventEmitter {
|
||||
this.terminalBuffer.clear();
|
||||
this.clearWorkingPatternWindow();
|
||||
|
||||
this.stepTimer = this.startTrackedTimer(
|
||||
this.stepTimerId = this.startTrackedTimer(
|
||||
'step-delay',
|
||||
this.config.interStepDelayMs,
|
||||
async () => {
|
||||
this.stepTimer = null;
|
||||
this.stepTimerId = null;
|
||||
if (this._state === 'stopped') return;
|
||||
const prompt = this.config.kickstartPrompt!;
|
||||
this.logAction('command', `Sending kickstart: "${prompt.substring(0, 40)}..."`);
|
||||
@@ -1773,46 +1780,20 @@ export class RespawnController extends EventEmitter {
|
||||
private clearTimers(): void {
|
||||
// Clear tracked timers map first to avoid stale entries during individual cleanup
|
||||
this.activeTimers.clear();
|
||||
if (this.stepTimer) {
|
||||
clearTimeout(this.stepTimer);
|
||||
this.stepTimer = null;
|
||||
}
|
||||
if (this.clearFallbackTimer) {
|
||||
clearTimeout(this.clearFallbackTimer);
|
||||
this.clearFallbackTimer = null;
|
||||
}
|
||||
if (this.completionConfirmTimer) {
|
||||
clearTimeout(this.completionConfirmTimer);
|
||||
this.completionConfirmTimer = null;
|
||||
}
|
||||
if (this.stepConfirmTimer) {
|
||||
clearTimeout(this.stepConfirmTimer);
|
||||
this.stepConfirmTimer = null;
|
||||
}
|
||||
if (this.autoAcceptTimer) {
|
||||
clearTimeout(this.autoAcceptTimer);
|
||||
this.autoAcceptTimer = null;
|
||||
}
|
||||
if (this.preFilterTimer) {
|
||||
clearTimeout(this.preFilterTimer);
|
||||
this.preFilterTimer = null;
|
||||
}
|
||||
if (this.noOutputTimer) {
|
||||
clearTimeout(this.noOutputTimer);
|
||||
this.noOutputTimer = null;
|
||||
}
|
||||
if (this.hookConfirmTimer) {
|
||||
clearTimeout(this.hookConfirmTimer);
|
||||
this.hookConfirmTimer = null;
|
||||
}
|
||||
if (this.stuckStateTimer) {
|
||||
clearInterval(this.stuckStateTimer);
|
||||
this.stuckStateTimer = null;
|
||||
}
|
||||
if (this.detectionUpdateTimer) {
|
||||
clearInterval(this.detectionUpdateTimer);
|
||||
this.detectionUpdateTimer = null;
|
||||
}
|
||||
this.cleanup.dispose();
|
||||
// Reinitialize for reuse (controller can be stopped and restarted)
|
||||
this.cleanup = new CleanupManager();
|
||||
// Null out IDs
|
||||
this.stepTimerId = null;
|
||||
this.completionConfirmTimerId = null;
|
||||
this.noOutputTimerId = null;
|
||||
this.detectionUpdateTimerId = null;
|
||||
this.autoAcceptTimerId = null;
|
||||
this.preFilterTimerId = null;
|
||||
this.hookConfirmTimerId = null;
|
||||
this.clearFallbackTimerId = null;
|
||||
this.stepConfirmTimerId = null;
|
||||
this.stuckStateTimerId = null;
|
||||
}
|
||||
|
||||
// ========== Stuck-State Detection Methods ==========
|
||||
@@ -1826,21 +1807,25 @@ export class RespawnController extends EventEmitter {
|
||||
if (this._state === 'stopped') return;
|
||||
|
||||
// Clear existing timer
|
||||
if (this.stuckStateTimer) {
|
||||
clearInterval(this.stuckStateTimer);
|
||||
this.stuckStateTimer = null;
|
||||
if (this.stuckStateTimerId) {
|
||||
this.cleanup.unregister(this.stuckStateTimerId);
|
||||
this.stuckStateTimerId = null;
|
||||
}
|
||||
|
||||
// Check interval for stuck state
|
||||
const checkIntervalMs = Math.min(this.config.stuckStateWarningMs, 60000); // Check every minute max
|
||||
|
||||
this.stuckStateTimer = setInterval(() => {
|
||||
try {
|
||||
this.checkStuckState();
|
||||
} catch (err) {
|
||||
console.error(`[RespawnController] Error in stuckStateTimer:`, err);
|
||||
}
|
||||
}, checkIntervalMs);
|
||||
this.stuckStateTimerId = this.cleanup.setInterval(
|
||||
() => {
|
||||
try {
|
||||
this.checkStuckState();
|
||||
} catch (err) {
|
||||
console.error(`[RespawnController] Error in stuckStateTimer:`, err);
|
||||
}
|
||||
},
|
||||
checkIntervalMs,
|
||||
{ description: 'stuck-state detection' }
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1981,7 +1966,7 @@ export class RespawnController extends EventEmitter {
|
||||
* Start a tracked timer with UI countdown support.
|
||||
* Emits timerStarted event and tracks the timer for UI display.
|
||||
*/
|
||||
private startTrackedTimer(name: string, durationMs: number, callback: () => void, reason?: string): NodeJS.Timeout {
|
||||
private startTrackedTimer(name: string, durationMs: number, callback: () => void, reason?: string): string {
|
||||
const now = Date.now();
|
||||
const endsAt = now + durationMs;
|
||||
|
||||
@@ -1989,19 +1974,23 @@ export class RespawnController extends EventEmitter {
|
||||
this.emit('timerStarted', { name, durationMs, endsAt, reason });
|
||||
this.logAction('timer', `Started ${name}: ${Math.round(durationMs / 1000)}s${reason ? ` (${reason})` : ''}`);
|
||||
|
||||
return setTimeout(() => {
|
||||
this.activeTimers.delete(name);
|
||||
this.emit('timerCompleted', name);
|
||||
callback();
|
||||
}, durationMs);
|
||||
return this.cleanup.setTimeout(
|
||||
() => {
|
||||
this.activeTimers.delete(name);
|
||||
this.emit('timerCompleted', name);
|
||||
callback();
|
||||
},
|
||||
durationMs,
|
||||
{ description: name }
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Cancel a tracked timer and emit cancellation event.
|
||||
*/
|
||||
private cancelTrackedTimer(name: string, timerRef: NodeJS.Timeout | null, reason?: string): void {
|
||||
if (timerRef) {
|
||||
clearTimeout(timerRef);
|
||||
private cancelTrackedTimer(name: string, timerId: string | null, reason?: string): void {
|
||||
if (timerId) {
|
||||
this.cleanup.unregister(timerId);
|
||||
if (this.activeTimers.has(name)) {
|
||||
this.activeTimers.delete(name);
|
||||
this.emit('timerCancelled', name, reason);
|
||||
@@ -2097,14 +2086,14 @@ export class RespawnController extends EventEmitter {
|
||||
* (used when AI check is disabled or has too many errors).
|
||||
*/
|
||||
private startNoOutputTimer(): void {
|
||||
this.cancelTrackedTimer('no-output-fallback', this.noOutputTimer, 'restarting');
|
||||
this.noOutputTimer = null;
|
||||
this.cancelTrackedTimer('no-output-fallback', this.noOutputTimerId, 'restarting');
|
||||
this.noOutputTimerId = null;
|
||||
|
||||
this.noOutputTimer = this.startTrackedTimer(
|
||||
this.noOutputTimerId = this.startTrackedTimer(
|
||||
'no-output-fallback',
|
||||
this.config.noOutputTimeoutMs,
|
||||
() => {
|
||||
this.noOutputTimer = null;
|
||||
this.noOutputTimerId = null;
|
||||
if (this._state === 'watching' || this._state === 'confirming_idle') {
|
||||
const msSinceOutput = Date.now() - this.lastOutputTime;
|
||||
this.logAction('detection', `No-output fallback: ${Math.round(msSinceOutput / 1000)}s silence`);
|
||||
@@ -2137,17 +2126,17 @@ export class RespawnController extends EventEmitter {
|
||||
* This provides an additional path to AI check even without a completion message.
|
||||
*/
|
||||
private startPreFilterTimer(): void {
|
||||
this.cancelTrackedTimer('pre-filter', this.preFilterTimer, 'restarting');
|
||||
this.preFilterTimer = null;
|
||||
this.cancelTrackedTimer('pre-filter', this.preFilterTimerId, 'restarting');
|
||||
this.preFilterTimerId = null;
|
||||
|
||||
// Only set up pre-filter when AI check is enabled
|
||||
if (!this.config.aiIdleCheckEnabled) return;
|
||||
|
||||
this.preFilterTimer = this.startTrackedTimer(
|
||||
this.preFilterTimerId = this.startTrackedTimer(
|
||||
'pre-filter',
|
||||
this.config.completionConfirmMs,
|
||||
() => {
|
||||
this.preFilterTimer = null;
|
||||
this.preFilterTimerId = null;
|
||||
if (this._state === 'watching') {
|
||||
const now = Date.now();
|
||||
const msSinceOutput = now - this.lastOutputTime;
|
||||
@@ -2252,18 +2241,18 @@ export class RespawnController extends EventEmitter {
|
||||
|
||||
if (result.verdict === 'IDLE') {
|
||||
// Cancel any pending confirmation timers - AI has spoken
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'AI verdict: IDLE');
|
||||
this.completionConfirmTimer = null;
|
||||
this.cancelTrackedTimer('pre-filter', this.preFilterTimer, 'AI verdict: IDLE');
|
||||
this.preFilterTimer = null;
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimerId, 'AI verdict: IDLE');
|
||||
this.completionConfirmTimerId = null;
|
||||
this.cancelTrackedTimer('pre-filter', this.preFilterTimerId, 'AI verdict: IDLE');
|
||||
this.preFilterTimerId = null;
|
||||
|
||||
this.logAction('ai-check', `Verdict: IDLE - ${result.reasoning}`);
|
||||
this.emit('aiCheckCompleted', result);
|
||||
this.onIdleConfirmed(`ai-check: idle (${result.reasoning})`);
|
||||
} else if (result.verdict === 'WORKING') {
|
||||
// Cancel timers and go to cooldown
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'AI verdict: WORKING');
|
||||
this.completionConfirmTimer = null;
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimerId, 'AI verdict: WORKING');
|
||||
this.completionConfirmTimerId = null;
|
||||
|
||||
this.logAction('ai-check', `Verdict: WORKING - ${result.reasoning}`);
|
||||
this.emit('aiCheckCompleted', result);
|
||||
@@ -2319,14 +2308,14 @@ export class RespawnController extends EventEmitter {
|
||||
* and no elicitation dialog was detected. Only handles plan mode approvals.
|
||||
*/
|
||||
private startAutoAcceptTimer(): void {
|
||||
this.cancelTrackedTimer('auto-accept', this.autoAcceptTimer, 'restarting');
|
||||
this.autoAcceptTimer = null;
|
||||
this.cancelTrackedTimer('auto-accept', this.autoAcceptTimerId, 'restarting');
|
||||
this.autoAcceptTimerId = null;
|
||||
|
||||
this.autoAcceptTimer = this.startTrackedTimer(
|
||||
this.autoAcceptTimerId = this.startTrackedTimer(
|
||||
'auto-accept',
|
||||
this.config.autoAcceptDelayMs,
|
||||
() => {
|
||||
this.autoAcceptTimer = null;
|
||||
this.autoAcceptTimerId = null;
|
||||
this.tryAutoAccept();
|
||||
},
|
||||
'plan mode detection'
|
||||
@@ -2338,8 +2327,8 @@ export class RespawnController extends EventEmitter {
|
||||
* Called when a completion message is detected (normal idle flow handles it).
|
||||
*/
|
||||
private cancelAutoAcceptTimer(): void {
|
||||
this.cancelTrackedTimer('auto-accept', this.autoAcceptTimer, 'cancelled');
|
||||
this.autoAcceptTimer = null;
|
||||
this.cancelTrackedTimer('auto-accept', this.autoAcceptTimerId, 'cancelled');
|
||||
this.autoAcceptTimerId = null;
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -2500,8 +2489,8 @@ export class RespawnController extends EventEmitter {
|
||||
}
|
||||
|
||||
// Cancel completion confirmation - auto-accept takes precedence
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'auto-accept');
|
||||
this.completionConfirmTimer = null;
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimerId, 'auto-accept');
|
||||
this.completionConfirmTimerId = null;
|
||||
this.completionMessageTime = null;
|
||||
|
||||
// Ensure we're in watching state (not confirming_idle or ai_checking)
|
||||
@@ -2555,12 +2544,12 @@ export class RespawnController extends EventEmitter {
|
||||
}
|
||||
|
||||
// Cancel completion confirm timer - hook takes precedence
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'Stop hook received');
|
||||
this.completionConfirmTimer = null;
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimerId, 'Stop hook received');
|
||||
this.completionConfirmTimerId = null;
|
||||
|
||||
// Cancel pre-filter timer - hook takes precedence
|
||||
this.cancelTrackedTimer('pre-filter', this.preFilterTimer, 'Stop hook received');
|
||||
this.preFilterTimer = null;
|
||||
this.cancelTrackedTimer('pre-filter', this.preFilterTimerId, 'Stop hook received');
|
||||
this.preFilterTimerId = null;
|
||||
|
||||
// Start short confirmation timer to handle race conditions
|
||||
// (e.g., Stop hook arrives but Claude immediately starts new work)
|
||||
@@ -2594,12 +2583,12 @@ export class RespawnController extends EventEmitter {
|
||||
}
|
||||
|
||||
// Cancel all other detection timers - this is definitive
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'idle_prompt received');
|
||||
this.completionConfirmTimer = null;
|
||||
this.cancelTrackedTimer('pre-filter', this.preFilterTimer, 'idle_prompt received');
|
||||
this.preFilterTimer = null;
|
||||
this.cancelTrackedTimer('no-output-fallback', this.noOutputTimer, 'idle_prompt received');
|
||||
this.noOutputTimer = null;
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimerId, 'idle_prompt received');
|
||||
this.completionConfirmTimerId = null;
|
||||
this.cancelTrackedTimer('pre-filter', this.preFilterTimerId, 'idle_prompt received');
|
||||
this.preFilterTimerId = null;
|
||||
this.cancelTrackedTimer('no-output-fallback', this.noOutputTimerId, 'idle_prompt received');
|
||||
this.noOutputTimerId = null;
|
||||
|
||||
// idle_prompt is an even stronger signal than Stop hook (60s+ idle)
|
||||
// Skip confirmation and go directly to idle
|
||||
@@ -2613,14 +2602,14 @@ export class RespawnController extends EventEmitter {
|
||||
* @param hookType - Which hook triggered this ('stop' or 'idle_prompt')
|
||||
*/
|
||||
private startHookConfirmTimer(hookType: 'stop' | 'idle_prompt'): void {
|
||||
this.cancelTrackedTimer('hook-confirm', this.hookConfirmTimer, 'restarting');
|
||||
this.hookConfirmTimer = null;
|
||||
this.cancelTrackedTimer('hook-confirm', this.hookConfirmTimerId, 'restarting');
|
||||
this.hookConfirmTimerId = null;
|
||||
|
||||
this.hookConfirmTimer = this.startTrackedTimer(
|
||||
this.hookConfirmTimerId = this.startTrackedTimer(
|
||||
'hook-confirm',
|
||||
RespawnController.HOOK_CONFIRM_DELAY_MS,
|
||||
() => {
|
||||
this.hookConfirmTimer = null;
|
||||
this.hookConfirmTimerId = null;
|
||||
|
||||
// Verify we haven't received new output since the hook arrived
|
||||
const hookTime = hookType === 'stop' ? this.stopHookTime : this.idlePromptTime;
|
||||
@@ -2694,17 +2683,17 @@ export class RespawnController extends EventEmitter {
|
||||
* After completion message, waits for output silence then triggers AI check.
|
||||
*/
|
||||
private startCompletionConfirmTimer(): void {
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'restarting');
|
||||
this.completionConfirmTimer = null;
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimerId, 'restarting');
|
||||
this.completionConfirmTimerId = null;
|
||||
|
||||
this.setState('confirming_idle');
|
||||
this.logAction('detection', 'Completion message found in output');
|
||||
|
||||
this.completionConfirmTimer = this.startTrackedTimer(
|
||||
this.completionConfirmTimerId = this.startTrackedTimer(
|
||||
'completion-confirm',
|
||||
this.config.completionConfirmMs,
|
||||
() => {
|
||||
this.completionConfirmTimer = null;
|
||||
this.completionConfirmTimerId = null;
|
||||
if (this._state === 'stopped') return;
|
||||
const msSinceOutput = Date.now() - this.lastOutputTime;
|
||||
if (msSinceOutput >= this.config.completionConfirmMs) {
|
||||
@@ -2725,8 +2714,8 @@ export class RespawnController extends EventEmitter {
|
||||
* Cancel completion confirmation if new activity detected.
|
||||
*/
|
||||
private cancelCompletionConfirm(): void {
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'activity detected');
|
||||
this.completionConfirmTimer = null;
|
||||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimerId, 'activity detected');
|
||||
this.completionConfirmTimerId = null;
|
||||
if (this._state === 'confirming_idle') {
|
||||
this.setState('watching');
|
||||
this.completionMessageTime = null;
|
||||
@@ -2739,14 +2728,14 @@ export class RespawnController extends EventEmitter {
|
||||
* This ensures Claude has finished processing before we send the next command.
|
||||
*/
|
||||
private startStepConfirmTimer(step: 'update' | 'init' | 'kickstart'): void {
|
||||
this.cancelTrackedTimer('step-confirm', this.stepConfirmTimer, 'restarting');
|
||||
this.stepConfirmTimer = null;
|
||||
this.cancelTrackedTimer('step-confirm', this.stepConfirmTimerId, 'restarting');
|
||||
this.stepConfirmTimerId = null;
|
||||
|
||||
this.stepConfirmTimer = this.startTrackedTimer(
|
||||
this.stepConfirmTimerId = this.startTrackedTimer(
|
||||
'step-confirm',
|
||||
this.config.completionConfirmMs,
|
||||
() => {
|
||||
this.stepConfirmTimer = null;
|
||||
this.stepConfirmTimerId = null;
|
||||
if (this._state === 'stopped') return;
|
||||
const msSinceOutput = Date.now() - this.lastOutputTime;
|
||||
|
||||
@@ -2779,8 +2768,8 @@ export class RespawnController extends EventEmitter {
|
||||
* Cancel step confirmation if working patterns detected.
|
||||
*/
|
||||
private cancelStepConfirm(): void {
|
||||
this.cancelTrackedTimer('step-confirm', this.stepConfirmTimer, 'working detected');
|
||||
this.stepConfirmTimer = null;
|
||||
this.cancelTrackedTimer('step-confirm', this.stepConfirmTimerId, 'working detected');
|
||||
this.stepConfirmTimerId = null;
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -2942,11 +2931,11 @@ export class RespawnController extends EventEmitter {
|
||||
this.terminalBuffer.clear(); // Clear buffer for fresh detection
|
||||
this.clearWorkingPatternWindow(); // Clear rolling window
|
||||
|
||||
this.stepTimer = this.startTrackedTimer(
|
||||
this.stepTimerId = this.startTrackedTimer(
|
||||
'step-delay',
|
||||
this.config.interStepDelayMs,
|
||||
async () => {
|
||||
this.stepTimer = null;
|
||||
this.stepTimerId = null;
|
||||
if (this._state === 'stopped') return;
|
||||
|
||||
// Use RALPH_STATUS RECOMMENDATION if available, otherwise fall back to config
|
||||
@@ -2983,11 +2972,11 @@ export class RespawnController extends EventEmitter {
|
||||
this.terminalBuffer.clear();
|
||||
this.clearWorkingPatternWindow();
|
||||
|
||||
this.stepTimer = this.startTrackedTimer(
|
||||
this.stepTimerId = this.startTrackedTimer(
|
||||
'step-delay',
|
||||
this.config.interStepDelayMs,
|
||||
async () => {
|
||||
this.stepTimer = null;
|
||||
this.stepTimerId = null;
|
||||
if (this._state === 'stopped') return;
|
||||
this.logAction('command', 'Sending: /clear');
|
||||
await this.session.writeViaMux('/clear\r'); // \r triggers Enter in Ink/Claude CLI
|
||||
@@ -2996,11 +2985,11 @@ export class RespawnController extends EventEmitter {
|
||||
this.promptDetected = false;
|
||||
|
||||
// Start fallback timer - if no prompt detected after 10s, proceed to /init anyway
|
||||
this.clearFallbackTimer = this.startTrackedTimer(
|
||||
this.clearFallbackTimerId = this.startTrackedTimer(
|
||||
'clear-fallback',
|
||||
RespawnController.CLEAR_FALLBACK_TIMEOUT_MS,
|
||||
() => {
|
||||
this.clearFallbackTimer = null;
|
||||
this.clearFallbackTimerId = null;
|
||||
if (this._state === 'waiting_clear') {
|
||||
this.logAction('step', '/clear fallback: proceeding to /init');
|
||||
this.emit('stepCompleted', 'clear');
|
||||
@@ -3027,11 +3016,11 @@ export class RespawnController extends EventEmitter {
|
||||
this.terminalBuffer.clear();
|
||||
this.clearWorkingPatternWindow();
|
||||
|
||||
this.stepTimer = this.startTrackedTimer(
|
||||
this.stepTimerId = this.startTrackedTimer(
|
||||
'step-delay',
|
||||
this.config.interStepDelayMs,
|
||||
async () => {
|
||||
this.stepTimer = null;
|
||||
this.stepTimerId = null;
|
||||
if (this._state === 'stopped') return;
|
||||
this.logAction('command', 'Sending: /init');
|
||||
await this.session.writeViaMux('/init\r'); // \r triggers Enter in Ink/Claude CLI
|
||||
|
||||
+12
-25
@@ -28,7 +28,7 @@ import {
|
||||
TokenStats,
|
||||
TokenUsageEntry,
|
||||
} from './types.js';
|
||||
import { MAX_SESSION_TOKENS } from './utils/index.js';
|
||||
import { Debouncer, MAX_SESSION_TOKENS } from './utils/index.js';
|
||||
|
||||
/** Debounce delay for batching state writes (ms) */
|
||||
const SAVE_DEBOUNCE_MS = 500;
|
||||
@@ -60,7 +60,7 @@ const MAX_CONSECUTIVE_FAILURES = 3;
|
||||
export class StateStore {
|
||||
private state: AppState;
|
||||
private filePath: string;
|
||||
private saveTimeout: NodeJS.Timeout | null = null;
|
||||
private saveDeb = new Debouncer(SAVE_DEBOUNCE_MS);
|
||||
private dirty: boolean = false;
|
||||
private dirtySessions = new Set<string>();
|
||||
private cachedSessionJsons = new Map<string, string>();
|
||||
@@ -68,7 +68,7 @@ export class StateStore {
|
||||
// Inner state storage (separate from main state to reduce write frequency)
|
||||
private ralphStates: Map<string, RalphSessionState> = new Map();
|
||||
private ralphStatePath: string;
|
||||
private ralphStateSaveTimeout: NodeJS.Timeout | null = null;
|
||||
private ralphStateSaveDeb = new Debouncer(SAVE_DEBOUNCE_MS);
|
||||
private ralphStateDirty: boolean = false;
|
||||
|
||||
// Circuit breaker for save failures (prevents hammering disk on persistent errors)
|
||||
@@ -150,14 +150,12 @@ export class StateStore {
|
||||
*/
|
||||
save(): void {
|
||||
this.dirty = true;
|
||||
if (this.saveTimeout) {
|
||||
return; // Already scheduled
|
||||
}
|
||||
this.saveTimeout = setTimeout(() => {
|
||||
if (this.saveDeb.isPending) return; // Already scheduled
|
||||
this.saveDeb.schedule(() => {
|
||||
this.saveNowAsync().catch((err) => {
|
||||
console.error('[StateStore] Async save failed:', err);
|
||||
});
|
||||
}, SAVE_DEBOUNCE_MS);
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -242,10 +240,7 @@ export class StateStore {
|
||||
}
|
||||
|
||||
private async _doSaveAsync(): Promise<void> {
|
||||
if (this.saveTimeout) {
|
||||
clearTimeout(this.saveTimeout);
|
||||
this.saveTimeout = null;
|
||||
}
|
||||
this.saveDeb.cancel();
|
||||
if (!this.dirty) {
|
||||
return;
|
||||
}
|
||||
@@ -332,10 +327,7 @@ export class StateStore {
|
||||
* Prefer saveNowAsync() for normal operation.
|
||||
*/
|
||||
saveNow(): void {
|
||||
if (this.saveTimeout) {
|
||||
clearTimeout(this.saveTimeout);
|
||||
this.saveTimeout = null;
|
||||
}
|
||||
this.saveDeb.cancel();
|
||||
if (!this.dirty) {
|
||||
return;
|
||||
}
|
||||
@@ -775,12 +767,10 @@ export class StateStore {
|
||||
// Debounced save for inner states
|
||||
private saveRalphStates(): void {
|
||||
this.ralphStateDirty = true;
|
||||
if (this.ralphStateSaveTimeout) {
|
||||
return; // Already scheduled
|
||||
}
|
||||
this.ralphStateSaveTimeout = setTimeout(() => {
|
||||
if (this.ralphStateSaveDeb.isPending) return; // Already scheduled
|
||||
this.ralphStateSaveDeb.schedule(() => {
|
||||
this.saveRalphStatesNow();
|
||||
}, SAVE_DEBOUNCE_MS);
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -788,10 +778,7 @@ export class StateStore {
|
||||
* Writes to temp file first, then renames to prevent corruption on crash.
|
||||
*/
|
||||
private saveRalphStatesNow(): void {
|
||||
if (this.ralphStateSaveTimeout) {
|
||||
clearTimeout(this.ralphStateSaveTimeout);
|
||||
this.ralphStateSaveTimeout = null;
|
||||
}
|
||||
this.ralphStateSaveDeb.cancel();
|
||||
if (!this.ralphStateDirty) {
|
||||
return;
|
||||
}
|
||||
|
||||
+72
-105
@@ -14,6 +14,7 @@ import { join, basename } from 'node:path';
|
||||
import { execFile } from 'node:child_process';
|
||||
import { readFile, readdir, stat as statAsync } from 'node:fs/promises';
|
||||
import { PENDING_TOOL_CALL_TTL_MS, MAX_PENDING_TOOL_CALLS } from './config/map-limits.js';
|
||||
import { CleanupManager, KeyedDebouncer } from './utils/index.js';
|
||||
|
||||
// ========== Types ==========
|
||||
|
||||
@@ -161,12 +162,11 @@ const FILE_CONTENT_DEBOUNCE_MS = 100; // Debounce delay for file content updates
|
||||
export class SubagentWatcher extends EventEmitter {
|
||||
private filePositions = new Map<string, number>();
|
||||
private dirWatchers = new Map<string, FSWatcher>();
|
||||
// Per-file debounce timers for directory watcher (replaces per-file FSWatchers)
|
||||
private fileDebouncers = new Map<string, NodeJS.Timeout>();
|
||||
// Per-file debouncer for directory watcher (replaces per-file FSWatchers)
|
||||
private fileDeb = new KeyedDebouncer(FILE_CONTENT_DEBOUNCE_MS);
|
||||
private agentInfo = new Map<string, SubagentInfo>();
|
||||
private idleTimers = new Map<string, NodeJS.Timeout>();
|
||||
private pollInterval: NodeJS.Timeout | null = null;
|
||||
private livenessInterval: NodeJS.Timeout | null = null;
|
||||
private idleDeb = new KeyedDebouncer(IDLE_TIMEOUT_MS);
|
||||
private cleanup = new CleanupManager();
|
||||
private _isRunning = false;
|
||||
private knownSubagentDirs = new Set<string>();
|
||||
// Map of agentId -> Map of toolUseId -> { toolName, timestamp } (for linking tool_result to tool_call)
|
||||
@@ -228,12 +228,16 @@ export class SubagentWatcher extends EventEmitter {
|
||||
// Periodic scan for new subagent directories
|
||||
// Full directory traversal only every FULL_SCAN_EVERY_N_POLLS polls (~5s)
|
||||
// FSWatchers handle known directories between full scans
|
||||
this.pollInterval = setInterval(() => {
|
||||
this._pollCount++;
|
||||
if (this._pollCount % FULL_SCAN_EVERY_N_POLLS === 0) {
|
||||
this.scanForSubagents().catch((err) => this.emit('subagent:error', err as Error));
|
||||
}
|
||||
}, POLL_INTERVAL_MS);
|
||||
this.cleanup.setInterval(
|
||||
() => {
|
||||
this._pollCount++;
|
||||
if (this._pollCount % FULL_SCAN_EVERY_N_POLLS === 0) {
|
||||
this.scanForSubagents().catch((err) => this.emit('subagent:error', err as Error));
|
||||
}
|
||||
},
|
||||
POLL_INTERVAL_MS,
|
||||
{ description: 'subagent directory poll' }
|
||||
);
|
||||
|
||||
// Periodic liveness check for active subagents
|
||||
this.startLivenessChecker();
|
||||
@@ -249,54 +253,56 @@ export class SubagentWatcher extends EventEmitter {
|
||||
* 3. Full pgrep scan (expensive, ~500ms) — only for agents that fail tiers 1+2
|
||||
*/
|
||||
private startLivenessChecker(): void {
|
||||
if (this.livenessInterval) return;
|
||||
this.cleanup.setInterval(
|
||||
async () => {
|
||||
// Guard: prevent concurrent liveness checks (avoids duplicate completed events)
|
||||
if (this._isCheckingLiveness) return;
|
||||
this._isCheckingLiveness = true;
|
||||
|
||||
this.livenessInterval = setInterval(async () => {
|
||||
// Guard: prevent concurrent liveness checks (avoids duplicate completed events)
|
||||
if (this._isCheckingLiveness) return;
|
||||
this._isCheckingLiveness = true;
|
||||
try {
|
||||
// Collect agents that need the expensive pgrep scan
|
||||
const needsFullScan: SubagentInfo[] = [];
|
||||
|
||||
try {
|
||||
// Collect agents that need the expensive pgrep scan
|
||||
const needsFullScan: SubagentInfo[] = [];
|
||||
|
||||
for (const [_agentId, info] of this.agentInfo) {
|
||||
if (info.status !== 'active' && info.status !== 'idle') continue;
|
||||
|
||||
// Tier 1: File mtime check (~0.3ms per agent)
|
||||
if (await this.checkSubagentFileAlive(info)) continue;
|
||||
|
||||
// Tier 2: Cached PID check (~0.1ms per agent)
|
||||
if (info.pid && (await this.checkPidAlive(info.pid))) continue;
|
||||
|
||||
// Tiers 1+2 failed — need expensive scan for this agent
|
||||
needsFullScan.push(info);
|
||||
}
|
||||
|
||||
// Tier 3: Full pgrep scan — only if any agents failed cheap checks
|
||||
if (needsFullScan.length > 0) {
|
||||
const pidMap = await this.getClaudePids();
|
||||
|
||||
for (const info of needsFullScan) {
|
||||
// Re-check status in case another check completed this agent
|
||||
for (const [_agentId, info] of this.agentInfo) {
|
||||
if (info.status !== 'active' && info.status !== 'idle') continue;
|
||||
|
||||
const alive = this.checkSubagentAliveFromPidMap(info, pidMap);
|
||||
if (!alive) {
|
||||
info.pid = undefined;
|
||||
info.status = 'completed';
|
||||
this.pendingToolCalls.delete(info.agentId);
|
||||
this.emit('subagent:completed', info);
|
||||
// Tier 1: File mtime check (~0.3ms per agent)
|
||||
if (await this.checkSubagentFileAlive(info)) continue;
|
||||
|
||||
// Tier 2: Cached PID check (~0.1ms per agent)
|
||||
if (info.pid && (await this.checkPidAlive(info.pid))) continue;
|
||||
|
||||
// Tiers 1+2 failed — need expensive scan for this agent
|
||||
needsFullScan.push(info);
|
||||
}
|
||||
|
||||
// Tier 3: Full pgrep scan — only if any agents failed cheap checks
|
||||
if (needsFullScan.length > 0) {
|
||||
const pidMap = await this.getClaudePids();
|
||||
|
||||
for (const info of needsFullScan) {
|
||||
// Re-check status in case another check completed this agent
|
||||
if (info.status !== 'active' && info.status !== 'idle') continue;
|
||||
|
||||
const alive = this.checkSubagentAliveFromPidMap(info, pidMap);
|
||||
if (!alive) {
|
||||
info.pid = undefined;
|
||||
info.status = 'completed';
|
||||
this.pendingToolCalls.delete(info.agentId);
|
||||
this.emit('subagent:completed', info);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Periodically clean up stale completed agents (older than 24 hours)
|
||||
this.cleanupStaleAgents();
|
||||
} finally {
|
||||
this._isCheckingLiveness = false;
|
||||
}
|
||||
}, LIVENESS_CHECK_MS);
|
||||
// Periodically clean up stale completed agents (older than 24 hours)
|
||||
this.cleanupStaleAgents();
|
||||
} finally {
|
||||
this._isCheckingLiveness = false;
|
||||
}
|
||||
},
|
||||
LIVENESS_CHECK_MS,
|
||||
{ description: 'subagent liveness check' }
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -418,21 +424,12 @@ export class SubagentWatcher extends EventEmitter {
|
||||
stop(): void {
|
||||
this._isRunning = false;
|
||||
|
||||
if (this.pollInterval) {
|
||||
clearInterval(this.pollInterval);
|
||||
this.pollInterval = null;
|
||||
}
|
||||
|
||||
if (this.livenessInterval) {
|
||||
clearInterval(this.livenessInterval);
|
||||
this.livenessInterval = null;
|
||||
}
|
||||
// Dispose poll and liveness intervals, then re-create for potential restart
|
||||
this.cleanup.dispose();
|
||||
this.cleanup = new CleanupManager();
|
||||
|
||||
// Clear file debouncers
|
||||
for (const timer of this.fileDebouncers.values()) {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
this.fileDebouncers.clear();
|
||||
this.fileDeb.dispose();
|
||||
this.fileAgentContext.clear();
|
||||
|
||||
// Remove error handlers before closing watchers to prevent memory leak
|
||||
@@ -447,10 +444,7 @@ export class SubagentWatcher extends EventEmitter {
|
||||
}
|
||||
this.dirWatchers.clear();
|
||||
|
||||
for (const timer of this.idleTimers.values()) {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
this.idleTimers.clear();
|
||||
this.idleDeb.dispose();
|
||||
|
||||
// Clear all state for clean restart
|
||||
this.filePositions.clear();
|
||||
@@ -532,16 +526,8 @@ export class SubagentWatcher extends EventEmitter {
|
||||
this.pendingToolCalls.delete(agentId);
|
||||
this.filePositions.delete(info.filePath);
|
||||
this.fileAgentContext.delete(info.filePath);
|
||||
const debounceTimer = this.fileDebouncers.get(info.filePath);
|
||||
if (debounceTimer) {
|
||||
clearTimeout(debounceTimer);
|
||||
this.fileDebouncers.delete(info.filePath);
|
||||
}
|
||||
const timer = this.idleTimers.get(agentId);
|
||||
if (timer) {
|
||||
clearTimeout(timer);
|
||||
this.idleTimers.delete(agentId);
|
||||
}
|
||||
this.fileDeb.cancelKey(info.filePath);
|
||||
this.idleDeb.cancelKey(agentId);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -634,9 +620,9 @@ export class SubagentWatcher extends EventEmitter {
|
||||
|
||||
return {
|
||||
agentCount: this.agentInfo.size,
|
||||
fileDebouncerCount: this.fileDebouncers.size,
|
||||
fileDebouncerCount: this.fileDeb.size,
|
||||
dirWatcherCount: this.dirWatchers.size,
|
||||
idleTimerCount: this.idleTimers.size,
|
||||
idleTimerCount: this.idleDeb.size,
|
||||
pendingToolCallsCount,
|
||||
knownDirsCount: this.knownSubagentDirs.size,
|
||||
filePositionsCount: this.filePositions.size,
|
||||
@@ -1129,13 +1115,8 @@ export class SubagentWatcher extends EventEmitter {
|
||||
if (!filename?.endsWith('.jsonl')) return;
|
||||
const filePath = join(dir, filename);
|
||||
|
||||
// Clear existing debounce for this file
|
||||
const existing = this.fileDebouncers.get(filePath);
|
||||
if (existing) clearTimeout(existing);
|
||||
|
||||
// Debounce 100ms to batch rapid writes
|
||||
const timer = setTimeout(() => {
|
||||
this.fileDebouncers.delete(filePath);
|
||||
this.fileDeb.schedule(filePath, () => {
|
||||
if (!existsSync(filePath)) return;
|
||||
|
||||
if (this.fileAgentContext.has(filePath)) {
|
||||
@@ -1145,9 +1126,7 @@ export class SubagentWatcher extends EventEmitter {
|
||||
// New file — register it
|
||||
this.registerAgentFile(filePath, projectHash, sessionId).catch(() => {});
|
||||
}
|
||||
}, FILE_CONTENT_DEBOUNCE_MS);
|
||||
|
||||
this.fileDebouncers.set(filePath, timer);
|
||||
});
|
||||
});
|
||||
|
||||
// Handle watcher errors to prevent unhandled exceptions
|
||||
@@ -1602,25 +1581,13 @@ export class SubagentWatcher extends EventEmitter {
|
||||
* Reset idle timer for an agent
|
||||
*/
|
||||
private resetIdleTimer(agentId: string): void {
|
||||
const existing = this.idleTimers.get(agentId);
|
||||
if (existing) {
|
||||
clearTimeout(existing);
|
||||
}
|
||||
|
||||
const timer = setTimeout(() => {
|
||||
// Guard against race condition: agent may have been deleted before timer fires
|
||||
this.idleDeb.schedule(agentId, () => {
|
||||
const info = this.agentInfo.get(agentId);
|
||||
if (!info) {
|
||||
// Agent was deleted - clean up timer reference
|
||||
this.idleTimers.delete(agentId);
|
||||
return;
|
||||
}
|
||||
if (!info) return;
|
||||
if (info.status === 'active') {
|
||||
info.status = 'idle';
|
||||
}
|
||||
}, IDLE_TIMEOUT_MS);
|
||||
|
||||
this.idleTimers.set(agentId, timer);
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
+1
-2
@@ -59,8 +59,7 @@ import { resolveOpenCodeDir } from './utils/opencode-cli-resolver.js';
|
||||
// Timing Constants
|
||||
// ============================================================================
|
||||
|
||||
/** Timeout for exec commands (5 seconds) */
|
||||
const EXEC_TIMEOUT_MS = 5000;
|
||||
import { EXEC_TIMEOUT_MS } from './config/exec-timeout.js';
|
||||
|
||||
/** Delay after tmux session creation — enough for detached tmux to be queryable */
|
||||
const TMUX_CREATION_WAIT_MS = 100;
|
||||
|
||||
@@ -12,9 +12,7 @@ import { execSync } from 'node:child_process';
|
||||
import { existsSync } from 'node:fs';
|
||||
import { delimiter, dirname, join } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
|
||||
/** Timeout for exec commands (5 seconds) */
|
||||
const EXEC_TIMEOUT_MS = 5000;
|
||||
import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
|
||||
|
||||
/** Common directories where the Claude CLI binary may be installed */
|
||||
const CLAUDE_SEARCH_DIRS = [
|
||||
|
||||
@@ -0,0 +1,174 @@
|
||||
/**
|
||||
* @fileoverview Debounce utilities to replace manual timer management.
|
||||
*
|
||||
* Two variants:
|
||||
* - `Debouncer` — single debounced operation (replaces timer + clearTimeout pattern)
|
||||
* - `KeyedDebouncer` — per-key debouncing (replaces Map<string, Timeout> pattern)
|
||||
*
|
||||
* Both integrate with CleanupManager via dispose().
|
||||
*
|
||||
* @module utils/debouncer
|
||||
*/
|
||||
|
||||
/**
|
||||
* Single-operation debouncer.
|
||||
*
|
||||
* Replaces the common pattern of:
|
||||
* ```
|
||||
* private timer: NodeJS.Timeout | null = null;
|
||||
* debounce(fn) { if (this.timer) clearTimeout(this.timer); this.timer = setTimeout(fn, delay); }
|
||||
* cancel() { if (this.timer) { clearTimeout(this.timer); this.timer = null; } }
|
||||
* ```
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* private saveDeb = new Debouncer(500);
|
||||
*
|
||||
* onChange() {
|
||||
* this.saveDeb.schedule(() => this.save());
|
||||
* }
|
||||
*
|
||||
* stop() {
|
||||
* this.saveDeb.dispose();
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export class Debouncer {
|
||||
private timer: NodeJS.Timeout | null = null;
|
||||
|
||||
constructor(private readonly delayMs: number) {}
|
||||
|
||||
/**
|
||||
* Schedule a debounced callback. Resets the timer on each call.
|
||||
* If a previous call is pending, it is cancelled.
|
||||
*/
|
||||
schedule(fn: () => void): void {
|
||||
this.cancel();
|
||||
this.timer = setTimeout(() => {
|
||||
this.timer = null;
|
||||
fn();
|
||||
}, this.delayMs);
|
||||
}
|
||||
|
||||
/** Cancel any pending execution without invoking the callback. */
|
||||
cancel(): void {
|
||||
if (this.timer) {
|
||||
clearTimeout(this.timer);
|
||||
this.timer = null;
|
||||
}
|
||||
}
|
||||
|
||||
/** Whether a callback is currently pending. */
|
||||
get isPending(): boolean {
|
||||
return this.timer !== null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Cancel pending callback and flush immediately.
|
||||
* Useful for shutdown: cancel the timer but run the action now.
|
||||
*
|
||||
* @param fn - The flush function to run (typically the same function passed to schedule)
|
||||
*/
|
||||
flush(fn: () => void): void {
|
||||
this.cancel();
|
||||
fn();
|
||||
}
|
||||
|
||||
/** Alias for cancel() — matches CleanupManager/Disposable convention. */
|
||||
dispose(): void {
|
||||
this.cancel();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Per-key debouncer for operations that need independent timers per resource.
|
||||
*
|
||||
* Replaces the common pattern of:
|
||||
* ```
|
||||
* private timers = new Map<string, NodeJS.Timeout>();
|
||||
* debounce(key, fn) {
|
||||
* const existing = this.timers.get(key);
|
||||
* if (existing) clearTimeout(existing);
|
||||
* this.timers.set(key, setTimeout(() => { this.timers.delete(key); fn(); }, delay));
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* private fileDebouncers = new KeyedDebouncer(100);
|
||||
*
|
||||
* onFileChange(path: string) {
|
||||
* this.fileDebouncers.schedule(path, () => this.processFile(path));
|
||||
* }
|
||||
*
|
||||
* stop() {
|
||||
* this.fileDebouncers.dispose();
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export class KeyedDebouncer {
|
||||
private timers = new Map<string, NodeJS.Timeout>();
|
||||
|
||||
constructor(private readonly delayMs: number) {}
|
||||
|
||||
/**
|
||||
* Schedule a debounced callback for a specific key.
|
||||
* Each key has its own independent timer.
|
||||
*/
|
||||
schedule(key: string, fn: () => void): void {
|
||||
this.cancelKey(key);
|
||||
this.timers.set(
|
||||
key,
|
||||
setTimeout(() => {
|
||||
this.timers.delete(key);
|
||||
fn();
|
||||
}, this.delayMs)
|
||||
);
|
||||
}
|
||||
|
||||
/** Cancel a pending callback for a specific key. */
|
||||
cancelKey(key: string): void {
|
||||
const existing = this.timers.get(key);
|
||||
if (existing) {
|
||||
clearTimeout(existing);
|
||||
this.timers.delete(key);
|
||||
}
|
||||
}
|
||||
|
||||
/** Whether a callback is pending for a specific key. */
|
||||
has(key: string): boolean {
|
||||
return this.timers.has(key);
|
||||
}
|
||||
|
||||
/** Number of active timers. */
|
||||
get size(): number {
|
||||
return this.timers.size;
|
||||
}
|
||||
|
||||
/** Get all currently active keys. */
|
||||
keys(): IterableIterator<string> {
|
||||
return this.timers.keys();
|
||||
}
|
||||
|
||||
/** Cancel all pending callbacks. */
|
||||
dispose(): void {
|
||||
for (const timer of this.timers.values()) {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
this.timers.clear();
|
||||
}
|
||||
|
||||
/**
|
||||
* Cancel all pending callbacks and run a flush function for each active key.
|
||||
* Useful for shutdown: cancel timers but run the action for each pending key.
|
||||
*
|
||||
* @param fn - Called once per active key with the key as argument
|
||||
*/
|
||||
flushAll(fn: (key: string) => void): void {
|
||||
const activeKeys = Array.from(this.timers.keys());
|
||||
this.dispose();
|
||||
for (const key of activeKeys) {
|
||||
fn(key);
|
||||
}
|
||||
}
|
||||
}
|
||||
+6
-1
@@ -9,14 +9,19 @@
|
||||
export { BufferAccumulator } from './buffer-accumulator.js';
|
||||
export { LRUMap, type LRUMapOptions } from './lru-map.js';
|
||||
export { CleanupManager, type TimerOptions } from './cleanup-manager.js';
|
||||
export { Debouncer, KeyedDebouncer } from './debouncer.js';
|
||||
export { StaleExpirationMap, type StaleExpirationMapOptions } from './stale-expiration-map.js';
|
||||
export {
|
||||
ANSI_ESCAPE_PATTERN_FULL,
|
||||
ANSI_ESCAPE_PATTERN_SIMPLE,
|
||||
TOKEN_PATTERN,
|
||||
SPINNER_PATTERN,
|
||||
createAnsiPatternFull,
|
||||
createAnsiPatternSimple,
|
||||
stripAnsi,
|
||||
SAFE_PATH_PATTERN,
|
||||
} from './regex-patterns.js';
|
||||
export { MAX_SESSION_TOKENS } from './token-validation.js';
|
||||
export { MAX_SESSION_TOKENS, validateTokenCounts, validateTokensAndCost } from './token-validation.js';
|
||||
export { stringSimilarity, fuzzyPhraseMatch, todoContentHash } from './string-similarity.js';
|
||||
export { assertNever } from './type-safety.js';
|
||||
export { wrapWithNice } from './nice-wrapper.js';
|
||||
|
||||
@@ -11,9 +11,7 @@ import { execSync } from 'node:child_process';
|
||||
import { existsSync } from 'node:fs';
|
||||
import { dirname, join } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
|
||||
/** Timeout for exec commands (5 seconds) */
|
||||
const EXEC_TIMEOUT_MS = 5000;
|
||||
import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
|
||||
|
||||
/** Common directories where the OpenCode CLI binary may be installed */
|
||||
const OPENCODE_SEARCH_DIRS = [
|
||||
|
||||
@@ -24,7 +24,7 @@
|
||||
* levenshteinDistance('hello', 'helo') // 1 (one deletion)
|
||||
* levenshteinDistance('COMPLETE', 'COMPLET') // 1 (one deletion)
|
||||
*/
|
||||
export function levenshteinDistance(a: string, b: string): number {
|
||||
function levenshteinDistance(a: string, b: string): number {
|
||||
// Ensure a is the shorter string for space efficiency
|
||||
if (a.length > b.length) {
|
||||
[a, b] = [b, a];
|
||||
@@ -91,22 +91,6 @@ export function stringSimilarity(a: string, b: string): number {
|
||||
return 1 - distance / maxLength;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if two strings are similar within a given threshold.
|
||||
*
|
||||
* @param a - First string
|
||||
* @param b - Second string
|
||||
* @param threshold - Minimum similarity ratio (default: 0.85 = 85% similar)
|
||||
* @returns True if similarity >= threshold
|
||||
*
|
||||
* @example
|
||||
* isSimilar('COMPLETE', 'COMPLET', 0.85) // true (87.5% similar)
|
||||
* isSimilar('COMPLETE', 'DONE', 0.85) // false (0% similar)
|
||||
*/
|
||||
export function isSimilar(a: string, b: string, threshold = 0.85): boolean {
|
||||
return stringSimilarity(a, b) >= threshold;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if two strings are similar with edit distance tolerance.
|
||||
* More intuitive for short strings than percentage-based threshold.
|
||||
@@ -120,7 +104,7 @@ export function isSimilar(a: string, b: string, threshold = 0.85): boolean {
|
||||
* isSimilarByDistance('COMPLETE', 'COMPLET', 2) // true (distance 1)
|
||||
* isSimilarByDistance('COMPLETE', 'COMP', 2) // false (distance 4)
|
||||
*/
|
||||
export function isSimilarByDistance(a: string, b: string, maxDistance = 2): boolean {
|
||||
function isSimilarByDistance(a: string, b: string, maxDistance = 2): boolean {
|
||||
return levenshteinDistance(a, b) <= maxDistance;
|
||||
}
|
||||
|
||||
@@ -136,7 +120,7 @@ export function isSimilarByDistance(a: string, b: string, maxDistance = 2): bool
|
||||
* normalizePhrase('TASK-DONE') // 'TASKDONE'
|
||||
* normalizePhrase('Task Done') // 'TASKDONE'
|
||||
*/
|
||||
export function normalizePhrase(phrase: string): string {
|
||||
function normalizePhrase(phrase: string): string {
|
||||
return phrase
|
||||
.toUpperCase()
|
||||
.replace(/[\s_\-.]+/g, '') // Remove whitespace, underscores, hyphens, dots
|
||||
|
||||
@@ -506,3 +506,42 @@ export const RalphLoopStartSchema = z.object({
|
||||
)
|
||||
.optional(),
|
||||
});
|
||||
|
||||
// ========== Inferred Types ==========
|
||||
|
||||
export type CreateSessionInput = z.infer<typeof CreateSessionSchema>;
|
||||
export type RunPromptInput = z.infer<typeof RunPromptSchema>;
|
||||
export type ResizeInput = z.infer<typeof ResizeSchema>;
|
||||
export type CreateCaseInput = z.infer<typeof CreateCaseSchema>;
|
||||
export type QuickStartInput = z.infer<typeof QuickStartSchema>;
|
||||
export type HookEventInput = z.infer<typeof HookEventSchema>;
|
||||
export type RespawnConfigInput = z.infer<typeof RespawnConfigSchema>;
|
||||
export type ConfigUpdateInput = z.infer<typeof ConfigUpdateSchema>;
|
||||
export type SettingsUpdateInput = z.infer<typeof SettingsUpdateSchema>;
|
||||
export type SessionInputWithLimitInput = z.infer<typeof SessionInputWithLimitSchema>;
|
||||
export type SessionNameInput = z.infer<typeof SessionNameSchema>;
|
||||
export type SessionColorInput = z.infer<typeof SessionColorSchema>;
|
||||
export type RalphConfigInput = z.infer<typeof RalphConfigSchema>;
|
||||
export type FixPlanImportInput = z.infer<typeof FixPlanImportSchema>;
|
||||
export type RalphPromptWriteInput = z.infer<typeof RalphPromptWriteSchema>;
|
||||
export type AutoClearInput = z.infer<typeof AutoClearSchema>;
|
||||
export type AutoCompactInput = z.infer<typeof AutoCompactSchema>;
|
||||
export type ImageWatcherInput = z.infer<typeof ImageWatcherSchema>;
|
||||
export type FlickerFilterInput = z.infer<typeof FlickerFilterSchema>;
|
||||
export type QuickRunInput = z.infer<typeof QuickRunSchema>;
|
||||
export type ScheduledRunInput = z.infer<typeof ScheduledRunSchema>;
|
||||
export type LinkCaseInput = z.infer<typeof LinkCaseSchema>;
|
||||
export type GeneratePlanInput = z.infer<typeof GeneratePlanSchema>;
|
||||
export type GeneratePlanDetailedInput = z.infer<typeof GeneratePlanDetailedSchema>;
|
||||
export type CancelPlanInput = z.infer<typeof CancelPlanSchema>;
|
||||
export type PlanTaskUpdateInput = z.infer<typeof PlanTaskUpdateSchema>;
|
||||
export type PlanTaskAddInput = z.infer<typeof PlanTaskAddSchema>;
|
||||
export type CpuLimitInput = z.infer<typeof CpuLimitSchema>;
|
||||
export type ModelConfigUpdateInput = z.infer<typeof ModelConfigUpdateSchema>;
|
||||
export type SubagentWindowStatesInput = z.infer<typeof SubagentWindowStatesSchema>;
|
||||
export type SubagentParentMapInput = z.infer<typeof SubagentParentMapSchema>;
|
||||
export type InteractiveRespawnInput = z.infer<typeof InteractiveRespawnSchema>;
|
||||
export type RespawnEnableInput = z.infer<typeof RespawnEnableSchema>;
|
||||
export type PushSubscribeInput = z.infer<typeof PushSubscribeSchema>;
|
||||
export type PushPreferencesUpdateInput = z.infer<typeof PushPreferencesUpdateSchema>;
|
||||
export type RalphLoopStartInput = z.infer<typeof RalphLoopStartSchema>;
|
||||
|
||||
+53
-79
@@ -123,7 +123,7 @@ import {
|
||||
RalphLoopStartSchema,
|
||||
isValidWorkingDir,
|
||||
} from './schemas.js';
|
||||
import { StaleExpirationMap } from '../utils/index.js';
|
||||
import { CleanupManager, KeyedDebouncer, StaleExpirationMap } from '../utils/index.js';
|
||||
import { MAX_CONCURRENT_SESSIONS, MAX_SSE_CLIENTS } from '../config/map-limits.js';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
@@ -420,16 +420,14 @@ export class WebServer extends EventEmitter {
|
||||
ttlMs: 5 * 60 * 1000, // 5 minutes - auto-expire stale session timing data
|
||||
refreshOnGet: false, // Don't refresh on reads, only on explicit sets
|
||||
});
|
||||
// Scheduled runs cleanup timer
|
||||
private scheduledCleanupTimer: NodeJS.Timeout | null = null;
|
||||
// Centralized cleanup for standalone timers (intervals + resettable timeouts)
|
||||
private cleanup = new CleanupManager();
|
||||
// SSE event batching
|
||||
private taskUpdateBatches: Map<string, { sessionId: string; task: BackgroundTask }> = new Map();
|
||||
private taskUpdateBatchTimer: NodeJS.Timeout | null = null;
|
||||
private taskUpdateBatchTimerId: string | null = null;
|
||||
// State update batching (reduce expensive toDetailedState() serialization)
|
||||
private stateUpdatePending: Set<string> = new Set();
|
||||
private stateUpdateTimer: NodeJS.Timeout | null = null;
|
||||
// SSE client health check timer
|
||||
private sseHealthCheckTimer: NodeJS.Timeout | null = null;
|
||||
private stateUpdateTimerId: string | null = null;
|
||||
// Flag to prevent new timers during shutdown
|
||||
private _isStopping: boolean = false;
|
||||
// Cached light state for SSE init (avoids rebuilding on every reconnect)
|
||||
@@ -439,14 +437,13 @@ export class WebServer extends EventEmitter {
|
||||
private cachedSessionsList: { data: unknown[]; timestamp: number } | null = null;
|
||||
// Token recording for daily stats (track what's been recorded to avoid double-counting)
|
||||
private lastRecordedTokens: Map<string, { input: number; output: number }> = new Map();
|
||||
private tokenRecordingTimer: NodeJS.Timeout | null = null;
|
||||
// Server startup time for respawn grace period calculation
|
||||
private readonly serverStartTime: number = Date.now();
|
||||
// Pending respawn start timers (for cleanup on shutdown)
|
||||
private pendingRespawnStarts: Map<string, NodeJS.Timeout> = new Map();
|
||||
// Active plan orchestrators (for cancellation via API)
|
||||
private activePlanOrchestrators: Map<string, PlanOrchestrator> = new Map();
|
||||
private persistDebounceTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
|
||||
private persistDeb = new KeyedDebouncer(100);
|
||||
// Grace period before starting restored respawn controllers (2 minutes)
|
||||
private static readonly RESPAWN_RESTORE_GRACE_PERIOD_MS = 2 * 60 * 1000;
|
||||
// Stored listener handlers for cleanup
|
||||
@@ -4646,18 +4643,12 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
|
||||
|
||||
/** Debounced wrapper — coalesces rapid persistSessionState calls per session */
|
||||
private persistSessionState(session: Session): void {
|
||||
const existing = this.persistDebounceTimers.get(session.id);
|
||||
if (existing) clearTimeout(existing);
|
||||
this.persistDebounceTimers.set(
|
||||
session.id,
|
||||
setTimeout(() => {
|
||||
this.persistDebounceTimers.delete(session.id);
|
||||
// Session may have been removed during debounce
|
||||
if (this.sessions.has(session.id)) {
|
||||
this._persistSessionStateNow(session);
|
||||
}
|
||||
}, 100)
|
||||
);
|
||||
this.persistDeb.schedule(session.id, () => {
|
||||
// Session may have been removed during debounce
|
||||
if (this.sessions.has(session.id)) {
|
||||
this._persistSessionStateNow(session);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
/** Persists full session state including respawn config to state.json */
|
||||
@@ -4845,11 +4836,7 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
|
||||
}
|
||||
|
||||
// Clear pending persist-debounce timer (prevents stale closure holding session ref)
|
||||
const pendingPersist = this.persistDebounceTimers.get(sessionId);
|
||||
if (pendingPersist) {
|
||||
clearTimeout(pendingPersist);
|
||||
this.persistDebounceTimers.delete(sessionId);
|
||||
}
|
||||
this.persistDeb.cancelKey(sessionId);
|
||||
|
||||
// Clear batches, per-session timers, and pending state updates
|
||||
this.terminalBatches.delete(sessionId);
|
||||
@@ -5079,11 +5066,7 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
|
||||
this.lastTerminalEventTime.delete(session.id);
|
||||
|
||||
// Clear pending persist-debounce timer
|
||||
const pendingPersist = this.persistDebounceTimers.get(session.id);
|
||||
if (pendingPersist) {
|
||||
clearTimeout(pendingPersist);
|
||||
this.persistDebounceTimers.delete(session.id);
|
||||
}
|
||||
this.persistDeb.cancelKey(session.id);
|
||||
|
||||
// Close any active file streams
|
||||
fileStreamManager.closeSessionStreams(session.id);
|
||||
@@ -6000,11 +5983,15 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
|
||||
const key = `${sessionId}:${task.id}`;
|
||||
this.taskUpdateBatches.set(key, { sessionId, task });
|
||||
|
||||
if (!this.taskUpdateBatchTimer) {
|
||||
this.taskUpdateBatchTimer = setTimeout(() => {
|
||||
this.flushTaskUpdateBatches();
|
||||
this.taskUpdateBatchTimer = null;
|
||||
}, TASK_UPDATE_BATCH_INTERVAL);
|
||||
if (!this.taskUpdateBatchTimerId) {
|
||||
this.taskUpdateBatchTimerId = this.cleanup.setTimeout(
|
||||
() => {
|
||||
this.taskUpdateBatchTimerId = null;
|
||||
this.flushTaskUpdateBatches();
|
||||
},
|
||||
TASK_UPDATE_BATCH_INTERVAL,
|
||||
{ description: 'task update batch flush' }
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -6031,11 +6018,15 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
|
||||
|
||||
this.stateUpdatePending.add(sessionId);
|
||||
|
||||
if (!this.stateUpdateTimer) {
|
||||
this.stateUpdateTimer = setTimeout(() => {
|
||||
this.flushStateUpdates();
|
||||
this.stateUpdateTimer = null;
|
||||
}, STATE_UPDATE_DEBOUNCE_INTERVAL);
|
||||
if (!this.stateUpdateTimerId) {
|
||||
this.stateUpdateTimerId = this.cleanup.setTimeout(
|
||||
() => {
|
||||
this.stateUpdateTimerId = null;
|
||||
this.flushStateUpdates();
|
||||
},
|
||||
STATE_UPDATE_DEBOUNCE_INTERVAL,
|
||||
{ description: 'state update debounce flush' }
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -6226,21 +6217,30 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
|
||||
process.env.CODEMAN_API_URL = `${protocol}://localhost:${this.port}`;
|
||||
|
||||
// Start scheduled runs cleanup timer
|
||||
this.scheduledCleanupTimer = setInterval(() => {
|
||||
this.cleanupScheduledRuns();
|
||||
}, SCHEDULED_CLEANUP_INTERVAL);
|
||||
this.cleanup.setInterval(
|
||||
() => {
|
||||
this.cleanupScheduledRuns();
|
||||
},
|
||||
SCHEDULED_CLEANUP_INTERVAL,
|
||||
{ description: 'scheduled runs cleanup' }
|
||||
);
|
||||
|
||||
// Start SSE client health check timer (prevents memory leaks from dead connections)
|
||||
this.sseHealthCheckTimer = setInterval(() => {
|
||||
this.cleanupDeadSSEClients();
|
||||
}, SSE_HEALTH_CHECK_INTERVAL);
|
||||
this.cleanup.setInterval(
|
||||
() => {
|
||||
this.cleanupDeadSSEClients();
|
||||
},
|
||||
SSE_HEALTH_CHECK_INTERVAL,
|
||||
{ description: 'SSE client health check' }
|
||||
);
|
||||
|
||||
// Start token recording timer (every 5 minutes for long-running sessions)
|
||||
this.tokenRecordingTimer = setInterval(
|
||||
this.cleanup.setInterval(
|
||||
() => {
|
||||
this.recordPeriodicTokenUsage();
|
||||
},
|
||||
5 * 60 * 1000
|
||||
5 * 60 * 1000,
|
||||
{ description: 'periodic token recording' }
|
||||
);
|
||||
|
||||
// Start subagent watcher for Claude Code background agent visibility (if enabled)
|
||||
@@ -6531,11 +6531,8 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
|
||||
// Set stopping flag to prevent new timer creation during shutdown
|
||||
this._isStopping = true;
|
||||
|
||||
// Clear SSE health check timer
|
||||
if (this.sseHealthCheckTimer) {
|
||||
clearInterval(this.sseHealthCheckTimer);
|
||||
this.sseHealthCheckTimer = null;
|
||||
}
|
||||
// Dispose all managed timers (intervals + resettable timeouts)
|
||||
this.cleanup.dispose();
|
||||
|
||||
// Gracefully close all SSE connections before clearing
|
||||
for (const client of this.sseClients) {
|
||||
@@ -6558,43 +6555,20 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
|
||||
this.terminalBatches.clear();
|
||||
this.terminalBatchSizes.clear();
|
||||
|
||||
if (this.taskUpdateBatchTimer) {
|
||||
clearTimeout(this.taskUpdateBatchTimer);
|
||||
this.taskUpdateBatchTimer = null;
|
||||
}
|
||||
this.taskUpdateBatches.clear();
|
||||
|
||||
if (this.stateUpdateTimer) {
|
||||
clearTimeout(this.stateUpdateTimer);
|
||||
this.stateUpdateTimer = null;
|
||||
}
|
||||
this.stateUpdatePending.clear();
|
||||
|
||||
// Clear token recording timer
|
||||
if (this.tokenRecordingTimer) {
|
||||
clearInterval(this.tokenRecordingTimer);
|
||||
this.tokenRecordingTimer = null;
|
||||
}
|
||||
this.lastRecordedTokens.clear();
|
||||
|
||||
// Clear scheduled cleanup timer
|
||||
if (this.scheduledCleanupTimer) {
|
||||
clearInterval(this.scheduledCleanupTimer);
|
||||
this.scheduledCleanupTimer = null;
|
||||
}
|
||||
|
||||
// Stop multiplexer and flush pending saves
|
||||
this.mux.destroy();
|
||||
|
||||
// Flush any pending persist-debounce timers and persist dirty sessions
|
||||
for (const [sessionId, timer] of this.persistDebounceTimers) {
|
||||
clearTimeout(timer);
|
||||
this.persistDeb.flushAll((sessionId) => {
|
||||
const session = this.sessions.get(sessionId);
|
||||
if (session) {
|
||||
this._persistSessionStateNow(session);
|
||||
}
|
||||
}
|
||||
this.persistDebounceTimers.clear();
|
||||
});
|
||||
|
||||
// Clear cached state
|
||||
this.cachedLightState = null;
|
||||
|
||||
@@ -126,7 +126,10 @@ describe('writeHooksConfig', () => {
|
||||
writeHooksConfig(testDir);
|
||||
const settingsPath = join(testDir, '.claude', 'settings.local.json');
|
||||
const content = readFileSync(settingsPath, 'utf-8');
|
||||
expect(() => JSON.parse(content)).not.toThrow();
|
||||
const parsed = JSON.parse(content);
|
||||
expect(parsed).toHaveProperty('hooks');
|
||||
expect(parsed.hooks).toHaveProperty('Notification');
|
||||
expect(parsed.hooks).toHaveProperty('Stop');
|
||||
});
|
||||
|
||||
it('should include hooks config in output', () => {
|
||||
|
||||
@@ -121,6 +121,7 @@ describe('ImageWatcher', () => {
|
||||
|
||||
it('should be safe to call for non-watched session', () => {
|
||||
expect(() => watcher.unwatchSession('nonexistent')).not.toThrow();
|
||||
expect(watcher.getWatchedSessions()).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should clear pending debounce timers for the session', () => {
|
||||
|
||||
@@ -214,6 +214,7 @@ describe('SessionManager', () => {
|
||||
|
||||
it('should handle non-existent session gracefully', async () => {
|
||||
await expect(manager.stopSession('non-existent')).resolves.not.toThrow();
|
||||
expect(manager.getSessionCount()).toBe(0);
|
||||
});
|
||||
|
||||
it('should update stored session to stopped', async () => {
|
||||
|
||||
@@ -536,9 +536,11 @@ describe('circular dependency detection', () => {
|
||||
|
||||
it('should allow dependencies on non-existent tasks (just unsatisfied, not a cycle)', () => {
|
||||
// Dependencies on non-existent tasks are valid - they just won't be satisfied
|
||||
expect(() => {
|
||||
queue.addTask({ prompt: 'Task D', dependencies: ['non-existent-id'] });
|
||||
}).not.toThrow();
|
||||
const task = queue.addTask({ prompt: 'Task D', dependencies: ['non-existent-id'] });
|
||||
expect(queue.getAllTasks()).toHaveLength(1);
|
||||
expect(task.dependencies).toEqual(['non-existent-id']);
|
||||
// Task is blocked by unsatisfied dependency, so next() should return null
|
||||
expect(queue.next()).toBeNull();
|
||||
});
|
||||
|
||||
it('should detect self-dependency when task references itself', () => {
|
||||
|
||||
@@ -564,14 +564,18 @@ describe('TaskTracker', () => {
|
||||
describe('Edge Cases', () => {
|
||||
it('should handle null message', () => {
|
||||
expect(() => tracker.processMessage(null)).not.toThrow();
|
||||
expect(tracker.getAllTasks().size).toBe(0);
|
||||
expect(tracker.getRunningCount()).toBe(0);
|
||||
});
|
||||
|
||||
it('should handle message without content', () => {
|
||||
expect(() => tracker.processMessage({ message: {} })).not.toThrow();
|
||||
expect(tracker.getAllTasks().size).toBe(0);
|
||||
});
|
||||
|
||||
it('should handle empty content array', () => {
|
||||
expect(() => tracker.processMessage({ message: { content: [] } })).not.toThrow();
|
||||
expect(tracker.getAllTasks().size).toBe(0);
|
||||
});
|
||||
|
||||
it('should handle tool_result for unknown task', () => {
|
||||
@@ -587,11 +591,15 @@ describe('TaskTracker', () => {
|
||||
},
|
||||
});
|
||||
}).not.toThrow();
|
||||
expect(tracker.getTask('unknown-task')).toBeUndefined();
|
||||
expect(tracker.getAllTasks().size).toBe(0);
|
||||
});
|
||||
|
||||
it('should handle empty terminal output', () => {
|
||||
expect(() => tracker.processTerminalOutput('')).not.toThrow();
|
||||
expect(() => tracker.processTerminalOutput(' ')).not.toThrow();
|
||||
expect(tracker.getAllTasks().size).toBe(0);
|
||||
expect(tracker.getRunningCount()).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
Reference in New Issue
Block a user