principles-disciple 1.40.0 → 1.42.0

package/.planning/codebase/ARCHITECTURE.md

@@ -0,0 +1,157 @@
+# Architecture
+
+**Analysis Date:** 2026-04-15
+
+## Pattern Overview
+
+**Overall:** Event-driven plugin architecture with hook-based interception
+
+**Key Characteristics:**
+- OpenClaw plugin framework with hook-based integration
+- Background worker services for async evolution processing
+- SQLite-based trajectory and state persistence
+- Multi-layer security gates (GFI gate, empathy engine, pain tracking)
+- Workflow managers for complex subagent orchestration
+
+## Layers
+
+**Plugin Entry Point:**
+- Purpose: Initialize plugin, register hooks, commands, tools, and services
+- Location: `src/index.ts`
+- Contains: Plugin registration, hook handlers, command registration
+- Depends on: OpenClaw SDK, all core modules
+
+**Hooks Layer:**
+- Purpose: Intercept and modify OpenClaw agent behavior
+- Location: `src/hooks/`
+- Contains: `prompt.ts` (before_prompt_build), `gate.ts` (before_tool_call), `pain.ts` (after_tool_call), `llm.ts` (llm_output), `lifecycle.ts` (before_reset, compaction), `subagent.ts` (subagent lifecycle)
+- Depends on: Core services, workspace context
+- Used by: OpenClaw event system
+
+**Core Services:**
+- Purpose: Business logic for evolution, pain tracking, trajectory, nocturnal training
+- Location: `src/core/` and `src/service/`
+- Contains: `evolution-engine.ts`, `trajectory.ts`, `nocturnal-trinity.ts`, `pain.ts`, `training-program.ts`, `pd-task-service.ts`
+- Depends on: Database, workspace context, config
+
+**Command Handlers:**
+- Purpose: Implement slash commands (e.g., `/pd-init`, `/pd-status`, `/pd-nocturnal-review`)
+- Location: `src/commands/`
+- Contains: 20+ command implementations
+- Depends on: Core services, workspace context
+
+**Workflow Managers (Subagent Workflow):**
+- Purpose: Orchestrate complex subagent workflows
+- Location: `src/service/subagent-workflow/`
+- Contains: `nocturnal-workflow-manager.ts`, `deep-reflect-workflow-manager.ts`, `empathy-observer-workflow-manager.ts`, `correction-observer-workflow-manager.ts`
+- Depends on: Evolution worker, core services
+
+**Database Layer:**
+- Purpose: Persist trajectory data, evolution state, workflow state
+- Location: `src/core/schema/` (migrations), `src/service/central-database.ts`
+- Contains: SQLite schema, migration runner, query services
+- Depends on: better-sqlite3
+
+**UI Layer:**
+- Purpose: React-based plugin UI for monitoring and control
+- Location: `ui/src/`
+- Contains: Pages (Overview, Evolution, Feedback, GateMonitor, Samples, ThinkingModels), components (Shell, ProtectedRoute), context (auth, theme)
+- Depends on: React, React Router, lucide-react
+
+**Utils:**
+- Purpose: Shared utilities (I/O, logging, retry, hashing, file locking)
+- Location: `src/utils/`
+- Contains: `io.ts` (atomic writes), `plugin-logger.ts`, `retry.ts`, `hashing.ts`, `file-lock.ts`
+
+## Data Flow
+
+**Agent Execution Flow:**
+1. OpenClaw fires `before_prompt_build` hook
+2. `hooks/prompt.ts` builds context injection (principles, thinking OS, focus, reflection log)
+3. OpenClaw generates response
+4. `hooks/llm.ts` analyzes LLM output for signals
+5. User triggers tool call
+6. `hooks/gate.ts` intercepts `before_tool_call` - evaluates risk, may block
+7. Tool executes
+8. `hooks/pain.ts` intercepts `after_tool_call` - tracks pain signals, empathy penalties
+
+**Evolution Flow:**
+1. `EvolutionWorkerService` polls `pain_candidates.json` periodically
+2. For each candidate, `evolution-engine.ts` evaluates and derives improvements
+3. `trajectory.ts` records behavior patterns
+4. Nocturnal training (`nocturnal-trinity.ts`) synthesizes improvements into rule updates
+5. `principle-tree-ledger.ts` manages principle lifecycle
+
+**Nocturnal Training Flow:**
+1. Candidate scoring via `nocturnal-candidate-scoring.ts`
+2. Target selection via `nocturnal-target-selector.ts`
+3. Rule implementation validation via `nocturnal-rule-implementation-validator.ts`
+4. Promotion via `promotion-gate.ts`
+
+## Key Abstractions
+
+**WorkspaceContext:**
+- Purpose: Encapsulates all state and services for a single workspace
+- Examples: `src/core/workspace-context.ts`
+- Pattern: Factory method `WorkspaceContext.fromHookContext()`
+
+**EvolutionEngine:**
+- Purpose: Core evolution processing logic
+- Examples: `src/core/evolution-engine.ts`
+- Pattern: Reducer pattern with typed actions
+
+**NocturnalTrinity:**
+- Purpose: Three-phase nocturnal training (dataset, training, evaluation)
+- Examples: `src/core/nocturnal-trinity.ts`
+- Pattern: Phase orchestration with contract validation
+
+**PainConfig:**
+- Purpose: Plugin configuration management
+- Examples: `src/core/config.ts`
+- Pattern: Singleton per workspace with file persistence
+
+**RuleHost:**
+- Purpose: Secure rule execution environment
+- Examples: `src/core/rule-host.ts`
+- Pattern: Sandboxed evaluation with permission checks
+
+## Entry Points
+
+**Plugin Entry:**
+- Location: `src/index.ts`
+- Triggers: OpenClaw loads plugin
+- Responsibilities: Register all hooks, commands, tools, services; initialize workspace
+
+**Command Entry:**
+- Location: `src/commands/*.ts`
+- Triggers: User invokes slash command (e.g., `/pd-init`)
+- Responsibilities: Validate input, delegate to core services, return formatted result
+
+**Service Entry:**
+- Location: `src/service/evolution-worker.ts`
+- Triggers: `before_prompt_build` fires (starts background worker)
+- Responsibilities: Process evolution queue, track pain signals, trigger training
+
+## Error Handling
+
+**Strategy:** Graceful degradation with logging
+
+**Patterns:**
+- Try-catch blocks in all hook handlers with error logging
+- `SystemLogger.log()` for critical errors
+- Workspace context error recording via `eventLog.recordHookExecution()`
+- Non-critical errors caught silently (trajectory collection)
+
+## Cross-Cutting Concerns
+
+**Logging:** `src/utils/plugin-logger.ts` - OpenClaw logger abstraction
+
+**Validation:** Schema validation via `@sinclair/typebox` for config and event types
+
+**Authentication:** OpenClaw session-based, agent ID extracted from session key
+
+**I/O Safety:** Atomic file writes via `atomicWriteFileSync()` in `src/utils/io.ts`
+
+---
+
+*Architecture analysis: 2026-04-15*

package/.planning/codebase/CONCERNS.md

@@ -0,0 +1,145 @@
+# Codebase Concerns
+
+**Analysis Date:** 2026-04-15
+
+## Tech Debt
+
+**Large Monolithic Files:**
+- Issue: `evolution-worker.ts` is 2689 lines, `nocturnal-trinity.ts` is 2429 lines. These exceed reasonable single-file thresholds and make debugging/profiling difficult.
+- Files: `src/service/evolution-worker.ts`, `src/core/nocturnal-trinity.ts`
+- Impact: Hard to trace bugs, no granular profiling, high risk of regression on modification
+- Fix approach: Break into smaller focused modules (e.g., queue-processor.ts, workflow-watchdog.ts, sleep-cycle.ts)
+
+**Type Safety Workarounds:**
+- Issue: Extensive use of `as any`, `as unknown`, and double casts (`as unknown as`) throughout the codebase
+- Files: `src/hooks/prompt.ts`, `src/hooks/subagent.ts`, `src/service/evolution-worker.ts`, `src/commands/promote-impl.ts`, `src/commands/rollback.ts`, `src/commands/pain.ts`
+- Impact: Type errors are silenced rather than fixed, runtime type mismatches can go undetected
+- Fix approach: Define proper shared type interfaces, use discriminated unions
+
+**Busy-Wait Retry Loops:**
+- Issue: `src/utils/io.ts` uses busy-wait spin loops (`while (Date.now() < end)`) for Windows file lock retries
+- Files: `src/utils/io.ts` (lines 32-33)
+- Impact: Consumes CPU while waiting; fails to yield to event loop
+- Fix approach: Use `setTimeout` delay or `fs.promises` with proper async retry
+
+**Unhandled Promise Rejections:**
+- Issue: Comments in `evolution-worker.ts` (line 182) reference unhandled rejections leaving workflows in limbo. Pattern of catch blocks that re-throw or log but don't always propagate.
+- Files: `src/service/evolution-worker.ts`
+- Impact: Workflows stuck in inconsistent state, silent failures
+- Fix approach: Ensure all async operations have proper error handlers; use `process.on('unhandledRejection')` logging
+
+**TODO Comments Not Addressed:**
+- Issue: One active TODO in `src/hooks/bash-risk.ts:18` — "Extract types from gate.ts related to bash risk analysis"
+- Files: `src/hooks/bash-risk.ts`
+
+## Known Bugs
+
+**Stale Active Workflows (#185):**
+- Symptoms: Workflows marked 'active' but subagent never responds, blocking queue processing
+- Files: `src/service/evolution-worker.ts` (runWorkflowWatchdog)
+- Trigger: Subagent crash or network failure during workflow execution
+- Workaround: Watchdog marks them as 'terminal_error' after 2x TTL
+
+**Orphaned Sessions (#188):**
+- Symptoms: Child session cleanup fails when subagent runtime unavailable
+- Files: `src/service/evolution-worker.ts` (cleanup path)
+- Trigger: Gateway-safe fallback fails
+- Workaround: Manual cleanup required
+
+**Sleep Reflection Timeout Recovery (#214, #219):**
+- Symptoms: `sleep_reflection` tasks stuck in 'in_progress' after worker crash
+- Files: `src/service/evolution-worker.ts` (lines 1122-1198)
+- Trigger: Worker crashes after claiming task but before writing result
+- Fix: Timeout recovery logic reclaims stuck tasks after `task_timeout_ms`
+
+## Security Considerations
+
+**Credential Detection in Logs:**
+- Risk: Sensitive data (passwords, tokens, api_keys) may leak into event logs or trajectory data
+- Files: `src/hooks/trajectory-collector.ts`, `src/core/nocturnal-arbiter.ts`, `src/core/nocturnal-compliance.ts`
+- Current mitigation: `SENSITIVE_KEY_PATTERN` regex filters known patterns
+- Recommendations: Extend pattern to cover more formats; add redaction before any async write
+
+**Gateway Token Auth:**
+- Risk: HTTP route in `principles-console-route.ts` uses Bearer token auth
+- Files: `src/http/principles-console-route.ts`
+- Current mitigation: Token comparison with configured value
+- Recommendations: Use constant-time comparison to prevent timing attacks
+
+**No eval() or Dynamic Code Execution:**
+- Status: Clean — no `eval()`, `new Function()`, or `dangerouslySetInnerHTML` found in codebase
+
+## Performance Bottlenecks
+
+**Session Persistence Timer Per Session:**
+- Problem: `session-tracker.ts` creates a `setTimeout` per session for delayed persistence writes
+- Files: `src/core/session-tracker.ts`
+- Cause: Timer per workspace/session scales poorly with many concurrent sessions
+- Improvement path: Use a single periodic sweep for all dirty sessions
+
+**Event Log Buffer Flush:**
+- Problem: 20-event buffer or 30-second flush interval — events can be lost on crash
+- Files: `src/core/event-log.ts`
+- Cause: Trade-off between I/O frequency and durability
+- Improvement path: Flush immediately on critical events (hook failures, errors)
+
+**Evolution Queue File Read on Every Cycle:**
+- Problem: `evolution-worker.ts` reads and parses the entire queue JSON file on each heartbeat
+- Files: `src/service/evolution-worker.ts` (queue loading at lines 1085-1110)
+- Cause: Full file read/parse despite incremental changes
+- Improvement path: Use SQLite or incremental updates
+
+**Focus History Compression Timestamp:**
+- Problem: `focus-history.ts` writes `Date.now().toString()` on every compression
+- Files: `src/core/focus-history.ts` (line 962)
+- Impact: File modified on every compress even if content unchanged
+
+## Fragile Areas
+
+**Workflow Store Queue Migration:**
+- Files: `src/service/evolution-worker.ts` (migrateQueueToV2), `src/service/subagent-workflow/workflow-store.ts`
+- Why fragile: Legacy queue format detection via type guards, migration happens on every cycle
+- Safe modification: Add version field, run migrations once at startup not per cycle
+
+**JSON.parse Without Try-Catch on Queue Items:**
+- Files: `src/service/evolution-worker.ts` (line 1148: `JSON.parse(failureEvent.payload_json)`)
+- Why fragile: Payload may be malformed, parse throws and is caught broadly
+- Safe modification: Validate JSON structure before parse
+
+**Nocturnal Trinity Runtime Adapter:**
+- Files: `src/core/nocturnal-trinity.ts` (TrinityRuntimeAdapter)
+- Why fragile: Uses `api.runtime.agent.runEmbeddedPiAgent()` which has specific requirements (provider/model must be explicit)
+- Safe modification: Ensure all trinity calls pass explicit provider/model
+
+## Dependencies at Risk
+
+**better-sqlite3 (^12.9.0):**
+- Risk: Native module requiring platform-specific rebuilds; may break on Node.js major version upgrades
+- Impact: Database operations fail, session/trajectory storage breaks
+- Migration plan: Consider `sql.js` (pure JS) or `node:sqlite` (built-in) for portability
+
+**@sinclair/typebox (^0.34.48):**
+- Risk: Used for runtime schema validation; newer versions may change behavior
+- Impact: Validation mismatches could allow invalid data through
+
+## Test Coverage Gaps
+
+**Untested Service Layer:**
+- What's not tested: `evolution-worker.ts` (2689 lines), `nocturnal-service.ts` (1584 lines)
+- Files: `src/service/evolution-worker.ts`, `src/service/nocturnal-service.ts`
+- Risk: High — service layer contains critical business logic
+- Priority: High
+
+**Untested Workflow Managers:**
+- What's not tested: `empathy-observer-workflow-manager.ts`, `deep-reflect-workflow-manager.ts`, `correction-observer-workflow-manager.ts`
+- Files: `src/service/subagent-workflow/`
+- Risk: Workflow spawning and result handling is untested
+
+**No Integration Tests for Queue Processing:**
+- What's not tested: Queue enqueue/dequeue cycle, migration path, error recovery
+- Files: `src/service/evolution-worker.ts` (queue operations)
+- Risk: Queue corruption or migration bugs go undetected
+
+---
+
+*Concerns audit: 2026-04-15*

package/.planning/codebase/CONVENTIONS.md

@@ -0,0 +1,148 @@
+# Coding Conventions
+
+**Analysis Date:** 2026-04-15
+
+## Naming Patterns
+
+**Files:**
+- PascalCase for modules: `detection-service.ts`, `risk-calculator.ts`
+- kebab-case for utilities with multiple exports: `retry.ts`, `hashing.ts`
+- `.test.ts` suffix for test files co-located in `tests/` directory
+
+**Directories:**
+- Flat structure under `src/`: `commands/`, `core/`, `hooks/`, `service/`, `utils/`
+- Tests mirror source structure in `tests/` parallel directory
+
+**Functions:**
+- camelCase: `normalizePath`, `handleBeforeToolCall`, `computeDynamicTimeout`
+- Verb prefixes for actions: `handle*`, `compute*`, `extract*`, `serialize*`
+- Getter-style for services: `DetectionService.get()`, `WorkspaceContext.fromHookContext()`
+
+**Types & Interfaces:**
+- PascalCase: `DeepReflectionSettings`, `PainSettings`, `GfiGateSettings`
+- Suffix for type variants: `*Types`, `*Contract`, `*Schema`
+- Barrel exports via `index.ts` in each directory
+
+## Code Style
+
+**Formatting:**
+- ESLint with `@typescript-eslint` plugin
+- No Prettier config detected (not enforced)
+- 2-space indentation
+- No trailing semicolons in ESLint config (but not explicitly disabled)
+
+**Key ESLint Rules:**
+```javascript
+'no-empty': 'error',
+'no-console': 'warn',
+'@typescript-eslint/no-explicit-any': 'warn',
+'@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+'@typescript-eslint/no-non-null-assertion': 'warn',
+```
+
+**Linting (test files relaxed):**
+```javascript
+'@typescript-eslint/no-explicit-any': 'off',
+'no-empty': 'warn',
+'no-console': 'off',
+```
+
+**Import Organization:**
+1. Node.js built-ins (`path`, `fs`, `os`)
+2. External packages (`vitest`, `better-sqlite3`)
+3. Internal modules (`../../src/core/...`, `./hooks/...`)
+4. Type-only imports use `import type` syntax
+
+**Path Aliases:**
+- No `paths` aliasing in `tsconfig.json`
+- Relative imports with `.js` extension for ESM compatibility: `from '../../src/utils/io.js'`
+
+## Error Handling
+
+**Patterns:**
+- Return `undefined` for "not found" / "allowed" cases (not exceptions)
+- Throw typed errors from `src/config/errors.ts`
+- Result objects with `allowed: boolean` for gate checks
+- Log warnings via `plugin-logger.ts` for non-critical failures
+
+**Example - Gate pattern:**
+```typescript
+// Return block result, not exceptions
+export function handleBeforeToolCall(event, ctx): BlockResult | undefined {
+  if (someCondition) {
+    return { block: true, blockReason: '...' };
+  }
+  return undefined; // Allowed
+}
+```
+
+**SQLite errors:**
+- Use `better-sqlite3` with synchronous API
+- Wrap in try/catch for migration failures
+
+## Logging
+
+**Framework:** `src/utils/plugin-logger.ts`
+
+**Patterns:**
+- Structured logging with levels: `warn`, `error`, `info`, `debug`
+- Context passed as object: `logger.warn({ context: 'Gate' }, 'message')`
+- No `console.log` in production paths (warn-only via ESLint)
+
+## Comments
+
+**When to Comment:**
+- Complex cross-platform logic (Windows EPERM handling in `atomicWriteFileSync`)
+- Magic numbers explained: `const RENAME_MAX_RETRIES = 3`
+- Task markers in tests: `// Task 4: Default Values Consistency Tests`
+
+**JSDoc:**
+- Used in config files and public APIs
+- Not enforced on internal functions
+
+## Function Design
+
+**Size:**
+- Prefer small, focused functions
+- Complex modules split into helpers (e.g., `rule-host-helpers.ts`)
+
+**Parameters:**
+- Max 3-4 parameters before grouping into options object
+- Destructure for clarity: `function ({ workspaceDir, stateDir })`
+
+**Return Values:**
+- Explicit return types in public APIs
+- `undefined` for "not applicable" vs `null` for "intentionally empty"
+
+## Module Design
+
+**Exports:**
+- Named exports preferred over default exports
+- Barrel `index.ts` files aggregate directory exports
+- Factory functions for singleton services: `DetectionService.get(dir)`
+
+**Service Pattern:**
+```typescript
+// Singleton pattern for stateful services
+class DetectionService {
+  private static instances = new Map<string, DetectionFunnel>();
+  
+  static get(stateDir: string): DetectionFunnel {
+    if (!instances.has(stateDir)) {
+      instances.set(stateDir, new DetectionFunnel(...));
+    }
+    return instances.get(stateDir);
+  }
+  
+  static reset(): void { instances.clear(); }
+}
+```
+
+**Static Analysis:**
+- Vitest used for unit tests
+- ESM modules with `.js` extension in imports
+- `"type": "module"` in `package.json`
+
+---
+
+*Convention analysis: 2026-04-15*

package/.planning/codebase/INTEGRATIONS.md

@@ -0,0 +1,81 @@
+# External Integrations
+
+**Analysis Date:** 2026-04-15
+
+## APIs & External Services
+
+**Plugin Framework:**
+- OpenClaw - Host application
+  - SDK/Client: `@openclaw/plugin-kit` (peer dependency, bundled as external)
+  - Communication: Plugin hook events (`before_prompt_build`, `before_tool_call`, `after_tool_call`, `llm_output`, `subagent_spawning`, `subagent_ended`, `before_reset`, `before_compaction`, `after_compaction`)
+  - Registration: Commands, tools, HTTP routes, background services
+
+## Data Storage
+
+**Databases:**
+- SQLite (better-sqlite3 12.9.0)
+  - Connection: File-based at `.state/trajectory.db`
+  - Schema managed via migration runner in `src/core/schema/migrations/`
+  - Migrations: 4 migrations (001-init-trajectory, 002-init-central, 003-init-workflow, 004-add-thinking-and-gfi)
+
+**File Storage:**
+- Local filesystem (workspace-relative paths)
+- Templates copied to workspace on init (`templates/` directory)
+- State persisted to `.state/` directory
+- Pain samples stored in `memory/pain/`
+
+**Caching:**
+- None detected (in-memory caching only)
+
+## Authentication & Identity
+
+**Auth Provider:**
+- OpenClaw native (session-based)
+  - Implementation: Session key extraction via `extractAgentIdFromSessionKey()` in `src/utils/session-key.ts`
+  - Agent identification via `agentId` from OpenClaw context
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- Plugin logger (`src/utils/plugin-logger.ts`)
+- System logger (`src/core/system-logger.ts`)
+- Hook execution recording via `WorkspaceContext.eventLog.recordHookExecution()`
+
+**Logs:**
+- File-based logs: `.state/memory/logs/SYSTEM.log`
+- Console output for errors during build/dev
+
+## CI/CD & Deployment
+
+**Hosting:**
+- OpenClaw plugin ecosystem
+- Published as npm package `principles-disciple`
+
+**CI Pipeline:**
+- Not detected (no GitHub Actions or similar)
+
+## Environment Configuration
+
+**Required env vars:**
+- None required (configuration via OpenClaw plugin config API)
+
+**Secrets location:**
+- OpenClaw plugin configuration (not file-based)
+
+## Webhooks & Callbacks
+
+**Incoming (via OpenClaw hooks):**
+- `before_prompt_build` - Prompt building stage
+- `before_tool_call` - Security gate before tool execution
+- `after_tool_call` - Pain/trust tracking after tool execution
+- `llm_output` - LLM response analysis
+- `subagent_spawning` - Subagent lifecycle
+- `subagent_ended` - Subagent completion
+- `before_reset` / `before_compaction` / `after_compaction` - Workspace lifecycle
+
+**Outgoing:**
+- HTTP routes registered via `api.registerHttpRoute()` in `src/http/principles-console-route.ts`
+
+---
+
+*Integration audit: 2026-04-15*

package/.planning/codebase/STACK.md

@@ -0,0 +1,87 @@
+# Technology Stack
+
+**Analysis Date:** 2026-04-15
+
+## Languages
+
+**Primary:**
+- TypeScript 6.0.2 - Core plugin development
+- JSX/TSX - UI components
+
+**Secondary:**
+- JavaScript (ES2022) - Build scripts and configuration
+
+## Runtime
+
+**Environment:**
+- Node.js 20 (build target via esbuild)
+
+**Package Manager:**
+- pnpm 9.x
+- Lockfile: `pnpm-lock.yaml` (present)
+
+## Frameworks
+
+**Core:**
+- OpenClaw Plugin SDK (peer dependency) - Plugin architecture framework
+- React 19.2.0 - UI layer
+- React Router 7.9.4 - UI routing
+
+**Database:**
+- better-sqlite3 12.9.0 - Local SQLite database for trajectory and state persistence
+
+**UI Components:**
+- lucide-react 1.7.0 - Icon library
+
+**Build:**
+- esbuild 0.28.0 - Bundling plugin code
+- TypeScript 6.0.2 - Type checking and compilation
+
+**Testing:**
+- Vitest 4.1.0 - Test runner
+- @vitest/coverage-v8 4.1.0 - Coverage reporting
+- jsdom 29.0.1 - DOM environment for React testing
+- @testing-library/react 16.3.0 - React component testing
+
+**Linting:**
+- ESLint 10.1.0 - Code linting
+- @typescript-eslint packages 8.58.0 - TypeScript ESLint support
+
+## Key Dependencies
+
+**Critical:**
+- `@sinclair/typebox` 0.34.48 - JSON schema type generation
+- `micromatch` 4.0.8 - Glob pattern matching for file paths
+
+**Database:**
+- `@types/better-sqlite3` 7.6.13 - TypeScript types for SQLite
+
+**HTTP/WebSocket:**
+- `ws` 8.18.0 - WebSocket support
+- `@types/ws` 8.5.13 - TypeScript types for WebSocket
+
+## Configuration
+
+**Environment:**
+- Plugin configuration via `openclaw.plugin.json`
+- Workspace-level settings in `.state/pain_settings.json`
+- No `.env` files (configuration is code-driven)
+
+**Build:**
+- `tsconfig.json` - TypeScript configuration (target: ES2022, module: ESNext)
+- `esbuild.config.js` - Bundle configuration
+- `vitest.config.ts` - Test configuration with layered projects (unit/integration)
+
+## Platform Requirements
+
+**Development:**
+- Node.js 20+
+- pnpm 9+
+
+**Production:**
+- OpenClaw >=2026.4.4 (peer dependency)
+- Node.js 20 runtime
+
+---
+
+*Stack analysis: 2026-04-15*