aicodeman 0.2.9 → 0.3.1

package/dist/types/respawn.d.ts

@@ -0,0 +1,271 @@
+/**
+ * @fileoverview Respawn controller type definitions.
+ *
+ * Covers the autonomous session cycling system: configuration, presets,
+ * per-cycle metrics, aggregate health scoring, and adaptive timing.
+ *
+ * Key exports:
+ * - RespawnConfig — full respawn settings (idle timeout, AI checks, adaptive timing, skip-clear)
+ * - PersistedRespawnConfig — subset saved to disk for mux session recovery
+ * - RespawnPreset — named preset for quick setup (solo-work, team-lead, overnight-autonomous, etc.)
+ * - RespawnCycleMetrics — per-cycle outcome tracking (duration, idle reason, steps, tokens)
+ * - RespawnAggregateMetrics — aggregate stats across cycles (success rate, p90 duration)
+ * - RalphLoopHealthScore — composite 0-100 health score with 5 component scores
+ * - HealthStatus — 'excellent' | 'good' | 'degraded' | 'critical'
+ * - TimingHistory — rolling window of timing data for adaptive adjustments
+ * - CycleOutcome — 'success' | 'stuck_recovery' | 'blocked' | 'error' | 'cancelled'
+ *
+ * Cross-domain relationships:
+ * - RespawnConfig is embedded in AppConfig.respawn (app-state) and SessionState.respawnConfig (session)
+ * - RalphLoopHealthScore.components.circuitBreaker derives from CircuitBreakerStatus (ralph domain)
+ * - RespawnCycleMetrics.sessionId links to SessionState.id (session domain)
+ *
+ * Served at `GET /api/sessions/:id/respawn` (config + state).
+ */
+/**
+ * Configuration for the Respawn Controller
+ *
+ * The respawn controller keeps interactive sessions productive by
+ * automatically cycling through update prompts when Claude goes idle.
+ */
+export interface RespawnConfig {
+    /** How long to wait after seeing prompt before considering truly idle (ms) */
+    idleTimeoutMs: number;
+    /** The prompt to send for updating docs */
+    updatePrompt: string;
+    /** Delay between sending steps (ms) */
+    interStepDelayMs: number;
+    /** Whether to enable respawn loop */
+    enabled: boolean;
+    /** Whether to send /clear after update prompt */
+    sendClear: boolean;
+    /** Whether to send /init after /clear */
+    sendInit: boolean;
+    /** Optional prompt to send if /init doesn't trigger work */
+    kickstartPrompt?: string;
+    /** Time to wait after completion message before confirming idle (ms) */
+    completionConfirmMs?: number;
+    /** Fallback timeout when no output received at all (ms) */
+    noOutputTimeoutMs?: number;
+    /** Whether to auto-accept plan mode prompts by pressing Enter (not questions) */
+    autoAcceptPrompts?: boolean;
+    /** Delay before auto-accepting plan mode prompts when no output and no completion message (ms) */
+    autoAcceptDelayMs?: number;
+    /** Whether AI idle check is enabled */
+    aiIdleCheckEnabled?: boolean;
+    /** Model to use for AI idle check */
+    aiIdleCheckModel?: string;
+    /** Maximum characters of terminal buffer for AI check */
+    aiIdleCheckMaxContext?: number;
+    /** Timeout for AI check in ms */
+    aiIdleCheckTimeoutMs?: number;
+    /** Cooldown after WORKING verdict in ms */
+    aiIdleCheckCooldownMs?: number;
+    /** Whether AI plan mode check is enabled for auto-accept */
+    aiPlanCheckEnabled?: boolean;
+    /** Model to use for AI plan mode check */
+    aiPlanCheckModel?: string;
+    /** Maximum characters of terminal buffer for plan check */
+    aiPlanCheckMaxContext?: number;
+    /** Timeout for AI plan check in ms */
+    aiPlanCheckTimeoutMs?: number;
+    /** Cooldown after NOT_PLAN_MODE verdict in ms */
+    aiPlanCheckCooldownMs?: number;
+    /** Whether to use adaptive timing based on historical patterns */
+    adaptiveTimingEnabled?: boolean;
+    /** Minimum value for adaptive completion confirm (ms) */
+    adaptiveMinConfirmMs?: number;
+    /** Maximum value for adaptive completion confirm (ms) */
+    adaptiveMaxConfirmMs?: number;
+    /** Whether to skip /clear when context is below threshold */
+    skipClearWhenLowContext?: boolean;
+    /** Token percentage threshold below which /clear is skipped (0-100) */
+    skipClearThresholdPercent?: number;
+    /** Whether to track and persist cycle metrics */
+    trackCycleMetrics?: boolean;
+}
+/**
+ * Outcome of a respawn cycle
+ */
+export type CycleOutcome = 'success' | 'stuck_recovery' | 'blocked' | 'error' | 'cancelled';
+/**
+ * Metrics for a single respawn cycle.
+ * Persisted for post-mortem analysis of long-running loops.
+ */
+export interface RespawnCycleMetrics {
+    /** Unique cycle ID (session-id:cycle-number) */
+    cycleId: string;
+    /** Session ID this cycle belongs to */
+    sessionId: string;
+    /** Cycle number within the session */
+    cycleNumber: number;
+    /** Timestamp when cycle started */
+    startedAt: number;
+    /** Timestamp when cycle completed */
+    completedAt: number;
+    /** Total duration of cycle (ms) */
+    durationMs: number;
+    /** What triggered idle detection */
+    idleReason: string;
+    /** Time spent detecting idle (from start of watching to idle confirmed) */
+    idleDetectionMs: number;
+    /** Steps completed in this cycle */
+    stepsCompleted: string[];
+    /** Whether /clear was skipped (P2-002) */
+    clearSkipped: boolean;
+    /** Outcome of the cycle */
+    outcome: CycleOutcome;
+    /** Error message if outcome is 'error' */
+    errorMessage?: string;
+    /** Token count at start of cycle */
+    tokenCountAtStart?: number;
+    /** Token count at end of cycle */
+    tokenCountAtEnd?: number;
+    /** Completion confirm time used (may be adaptive) */
+    completionConfirmMsUsed: number;
+}
+/**
+ * Aggregate metrics across multiple cycles for health scoring.
+ */
+export interface RespawnAggregateMetrics {
+    /** Total cycles tracked */
+    totalCycles: number;
+    /** Successful cycles */
+    successfulCycles: number;
+    /** Cycles that required stuck-state recovery */
+    stuckRecoveryCycles: number;
+    /** Blocked cycles */
+    blockedCycles: number;
+    /** Error cycles */
+    errorCycles: number;
+    /** Average cycle duration (ms) */
+    avgCycleDurationMs: number;
+    /** Average idle detection time (ms) */
+    avgIdleDetectionMs: number;
+    /** 90th percentile cycle duration (ms) */
+    p90CycleDurationMs: number;
+    /** Success rate (0-100) */
+    successRate: number;
+    /** Last updated timestamp */
+    lastUpdatedAt: number;
+}
+/**
+ * Health status levels for the Ralph Loop system.
+ */
+export type HealthStatus = 'excellent' | 'good' | 'degraded' | 'critical';
+/**
+ * Comprehensive health score for a Ralph Loop session.
+ * Aggregates multiple health signals into a single score.
+ */
+export interface RalphLoopHealthScore {
+    /** Overall health score (0-100) */
+    score: number;
+    /** Health status based on score thresholds */
+    status: HealthStatus;
+    /** Individual component scores (0-100 each) */
+    components: {
+        /** Based on recent cycle success rate */
+        cycleSuccess: number;
+        /** Based on circuit breaker state */
+        circuitBreaker: number;
+        /** Based on iteration stall metrics */
+        iterationProgress: number;
+        /** Based on AI checker error rate */
+        aiChecker: number;
+        /** Based on stuck-state recovery count */
+        stuckRecovery: number;
+    };
+    /** Human-readable summary of health */
+    summary: string;
+    /** Recommendations for improvement */
+    recommendations: string[];
+    /** Timestamp when score was calculated */
+    calculatedAt: number;
+}
+/**
+ * Historical timing data for adaptive adjustments.
+ */
+export interface TimingHistory {
+    /** Rolling window of recent idle detection durations (ms) */
+    recentIdleDetectionMs: number[];
+    /** Rolling window of recent cycle durations (ms) */
+    recentCycleDurationMs: number[];
+    /** Calculated adaptive completion confirm value (ms) */
+    adaptiveCompletionConfirmMs: number;
+    /** Number of samples in rolling windows */
+    sampleCount: number;
+    /** Maximum samples to keep */
+    maxSamples: number;
+    /** Last updated timestamp */
+    lastUpdatedAt: number;
+}
+/**
+ * Named respawn configuration preset for quick setup
+ */
+export interface RespawnPreset {
+    /** Unique preset identifier */
+    id: string;
+    /** User-friendly preset name */
+    name: string;
+    /** Description of when to use this preset */
+    description?: string;
+    /** The respawn configuration (without enabled flag) */
+    config: Omit<RespawnConfig, 'enabled'>;
+    /** Duration in minutes (optional default) */
+    durationMinutes?: number;
+    /** Whether this is a built-in preset */
+    builtIn?: boolean;
+    /** Timestamp when created */
+    createdAt: number;
+}
+/**
+ * Persisted respawn configuration for mux sessions.
+ * Subset of RespawnConfig that gets saved to disk.
+ */
+export interface PersistedRespawnConfig {
+    /** Whether respawn was enabled */
+    enabled: boolean;
+    /** How long to wait after seeing prompt before considering truly idle (ms) */
+    idleTimeoutMs: number;
+    /** The prompt to send for updating docs */
+    updatePrompt: string;
+    /** Delay between sending steps (ms) */
+    interStepDelayMs: number;
+    /** Whether to send /clear after update prompt */
+    sendClear: boolean;
+    /** Whether to send /init after /clear */
+    sendInit: boolean;
+    /** Optional prompt to send if /init doesn't trigger work */
+    kickstartPrompt?: string;
+    /** Whether to auto-accept plan mode prompts by pressing Enter (not questions) */
+    autoAcceptPrompts?: boolean;
+    /** Delay before auto-accepting prompts (ms) */
+    autoAcceptDelayMs?: number;
+    /** Time to wait after completion message before confirming idle (ms) */
+    completionConfirmMs?: number;
+    /** Fallback timeout when no output received at all (ms) */
+    noOutputTimeoutMs?: number;
+    /** Whether AI idle check is enabled */
+    aiIdleCheckEnabled?: boolean;
+    /** Model to use for AI idle check */
+    aiIdleCheckModel?: string;
+    /** Maximum characters of terminal buffer for AI check */
+    aiIdleCheckMaxContext?: number;
+    /** Timeout for AI check in ms */
+    aiIdleCheckTimeoutMs?: number;
+    /** Cooldown after WORKING verdict in ms */
+    aiIdleCheckCooldownMs?: number;
+    /** Whether AI plan mode check is enabled for auto-accept */
+    aiPlanCheckEnabled?: boolean;
+    /** Model to use for AI plan mode check */
+    aiPlanCheckModel?: string;
+    /** Maximum characters of terminal buffer for plan check */
+    aiPlanCheckMaxContext?: number;
+    /** Timeout for AI plan check in ms */
+    aiPlanCheckTimeoutMs?: number;
+    /** Cooldown after NOT_PLAN_MODE verdict in ms */
+    aiPlanCheckCooldownMs?: number;
+    /** Duration in minutes if timed respawn was set */
+    durationMinutes?: number;
+}
+//# sourceMappingURL=respawn.d.ts.map

package/dist/types/respawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"respawn.d.ts","sourceRoot":"","sources":["../../src/types/respawn.ts"],"names":[],"mappings":"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"}

package/dist/types/respawn.js

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Respawn controller type definitions.
+ *
+ * Covers the autonomous session cycling system: configuration, presets,
+ * per-cycle metrics, aggregate health scoring, and adaptive timing.
+ *
+ * Key exports:
+ * - RespawnConfig — full respawn settings (idle timeout, AI checks, adaptive timing, skip-clear)
+ * - PersistedRespawnConfig — subset saved to disk for mux session recovery
+ * - RespawnPreset — named preset for quick setup (solo-work, team-lead, overnight-autonomous, etc.)
+ * - RespawnCycleMetrics — per-cycle outcome tracking (duration, idle reason, steps, tokens)
+ * - RespawnAggregateMetrics — aggregate stats across cycles (success rate, p90 duration)
+ * - RalphLoopHealthScore — composite 0-100 health score with 5 component scores
+ * - HealthStatus — 'excellent' | 'good' | 'degraded' | 'critical'
+ * - TimingHistory — rolling window of timing data for adaptive adjustments
+ * - CycleOutcome — 'success' | 'stuck_recovery' | 'blocked' | 'error' | 'cancelled'
+ *
+ * Cross-domain relationships:
+ * - RespawnConfig is embedded in AppConfig.respawn (app-state) and SessionState.respawnConfig (session)
+ * - RalphLoopHealthScore.components.circuitBreaker derives from CircuitBreakerStatus (ralph domain)
+ * - RespawnCycleMetrics.sessionId links to SessionState.id (session domain)
+ *
+ * Served at `GET /api/sessions/:id/respawn` (config + state).
+ */
+export {};
+//# sourceMappingURL=respawn.js.map

package/dist/types/respawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"respawn.js","sourceRoot":"","sources":["../../src/types/respawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}

package/dist/types/run-summary.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Run summary type definitions.
+ *
+ * Types for the "what happened while away" session timeline. RunSummary
+ * aggregates events (respawn cycles, errors, token milestones, AI checks)
+ * into a per-session historical view.
+ *
+ * Key exports:
+ * - RunSummary — complete per-session summary (events timeline + aggregated stats)
+ * - RunSummaryEvent — a single timestamped event (16 event types, 4 severity levels)
+ * - RunSummaryStats — aggregated metrics (cycles, tokens, active/idle time, error count)
+ * - RunSummaryEventType — union of event types (session_started, respawn_cycle_*, error, etc.)
+ * - RunSummaryEventSeverity — 'info' | 'warning' | 'error' | 'success'
+ * - createInitialRunSummaryStats() — factory for fresh stats
+ *
+ * Cross-domain: RunSummary.sessionId links to SessionState.id (session domain).
+ * In-memory only (not persisted to disk). Served at `GET /api/sessions/:id/run-summary`.
+ */
+/**
+ * Types of events tracked in the run summary.
+ * These provide a historical view of what happened during a session.
+ */
+export type RunSummaryEventType = 'session_started' | 'session_stopped' | 'respawn_cycle_started' | 'respawn_cycle_completed' | 'respawn_state_change' | 'error' | 'warning' | 'token_milestone' | 'auto_compact' | 'auto_clear' | 'idle_detected' | 'working_detected' | 'ralph_completion' | 'ai_check_result' | 'hook_event' | 'state_stuck';
+/**
+ * Severity levels for run summary events.
+ */
+export type RunSummaryEventSeverity = 'info' | 'warning' | 'error' | 'success';
+/**
+ * A single event in the run summary timeline.
+ */
+export interface RunSummaryEvent {
+    /** Unique event identifier */
+    id: string;
+    /** Timestamp when event occurred */
+    timestamp: number;
+    /** Type of event */
+    type: RunSummaryEventType;
+    /** Severity level for display */
+    severity: RunSummaryEventSeverity;
+    /** Short title for the event */
+    title: string;
+    /** Optional detailed description */
+    details?: string;
+    /** Optional additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Statistics aggregated from run summary events.
+ */
+export interface RunSummaryStats {
+    /** Number of respawn cycles completed */
+    totalRespawnCycles: number;
+    /** Total tokens used during this run */
+    totalTokensUsed: number;
+    /** Peak token count observed */
+    peakTokens: number;
+    /** Total time Claude was actively working (ms) */
+    totalTimeActiveMs: number;
+    /** Total time Claude was idle (ms) */
+    totalTimeIdleMs: number;
+    /** Number of errors encountered */
+    errorCount: number;
+    /** Number of warnings encountered */
+    warningCount: number;
+    /** Number of AI idle checks performed */
+    aiCheckCount: number;
+    /** Timestamp when last became idle */
+    lastIdleAt: number | null;
+    /** Timestamp when last started working */
+    lastWorkingAt: number | null;
+    /** Total number of state transitions */
+    stateTransitions: number;
+}
+/**
+ * Complete run summary for a session.
+ * Provides a historical view of session activity for users returning after absence.
+ */
+export interface RunSummary {
+    /** Session ID this summary belongs to */
+    sessionId: string;
+    /** Session display name */
+    sessionName: string;
+    /** Timestamp when tracking started */
+    startedAt: number;
+    /** Timestamp of last update */
+    lastUpdatedAt: number;
+    /** Timeline of events (most recent last) */
+    events: RunSummaryEvent[];
+    /** Aggregated statistics */
+    stats: RunSummaryStats;
+}
+/**
+ * Creates initial run summary stats.
+ */
+export declare function createInitialRunSummaryStats(): RunSummaryStats;
+//# sourceMappingURL=run-summary.d.ts.map

package/dist/types/run-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-summary.d.ts","sourceRoot":"","sources":["../../src/types/run-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B,iBAAiB,GACjB,iBAAiB,GACjB,uBAAuB,GACvB,yBAAyB,GACzB,sBAAsB,GACtB,OAAO,GACP,SAAS,GACT,iBAAiB,GACjB,cAAc,GACd,YAAY,GACZ,eAAe,GACf,kBAAkB,GAClB,kBAAkB,GAClB,iBAAiB,GACjB,YAAY,GACZ,aAAa,CAAC;AAElB;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,iCAAiC;IACjC,QAAQ,EAAE,uBAAuB,CAAC;IAClC,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wCAAwC;IACxC,eAAe,EAAE,MAAM,CAAC;IACxB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sCAAsC;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0CAA0C;IAC1C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,4BAA4B;IAC5B,KAAK,EAAE,eAAe,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,4BAA4B,IAAI,eAAe,CAc9D"}

package/dist/types/run-summary.js

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Run summary type definitions.
+ *
+ * Types for the "what happened while away" session timeline. RunSummary
+ * aggregates events (respawn cycles, errors, token milestones, AI checks)
+ * into a per-session historical view.
+ *
+ * Key exports:
+ * - RunSummary — complete per-session summary (events timeline + aggregated stats)
+ * - RunSummaryEvent — a single timestamped event (16 event types, 4 severity levels)
+ * - RunSummaryStats — aggregated metrics (cycles, tokens, active/idle time, error count)
+ * - RunSummaryEventType — union of event types (session_started, respawn_cycle_*, error, etc.)
+ * - RunSummaryEventSeverity — 'info' | 'warning' | 'error' | 'success'
+ * - createInitialRunSummaryStats() — factory for fresh stats
+ *
+ * Cross-domain: RunSummary.sessionId links to SessionState.id (session domain).
+ * In-memory only (not persisted to disk). Served at `GET /api/sessions/:id/run-summary`.
+ */
+/**
+ * Creates initial run summary stats.
+ */
+export function createInitialRunSummaryStats() {
+    return {
+        totalRespawnCycles: 0,
+        totalTokensUsed: 0,
+        peakTokens: 0,
+        totalTimeActiveMs: 0,
+        totalTimeIdleMs: 0,
+        errorCount: 0,
+        warningCount: 0,
+        aiCheckCount: 0,
+        lastIdleAt: null,
+        lastWorkingAt: null,
+        stateTransitions: 0,
+    };
+}
+//# sourceMappingURL=run-summary.js.map

package/dist/types/run-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-summary.js","sourceRoot":"","sources":["../../src/types/run-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgGH;;GAEG;AACH,MAAM,UAAU,4BAA4B;IAC1C,OAAO;QACL,kBAAkB,EAAE,CAAC;QACrB,eAAe,EAAE,CAAC;QAClB,UAAU,EAAE,CAAC;QACb,iBAAiB,EAAE,CAAC;QACpB,eAAe,EAAE,CAAC;QAClB,UAAU,EAAE,CAAC;QACb,YAAY,EAAE,CAAC;QACf,YAAY,EAAE,CAAC;QACf,UAAU,EAAE,IAAI;QAChB,aAAa,EAAE,IAAI;QACnB,gBAAgB,EAAE,CAAC;KACpB,CAAC;AACJ,CAAC"}

package/dist/types/session.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Session type definitions.
+ *
+ * Core domain type — SessionState is the primary entity in the system.
+ *
+ * Key exports:
+ * - SessionState — full session state (status, tokens, respawn, ralph, CLI metadata)
+ * - SessionConfig — creation-time config (id, workingDir, createdAt)
+ * - SessionOutput — captured stdout/stderr/exitCode
+ * - SessionStatus — 'idle' | 'busy' | 'stopped' | 'error'
+ * - SessionMode — 'claude' | 'shell' | 'opencode' (which CLI backend)
+ * - ClaudeMode — CLI permission mode ('dangerously-skip-permissions' | 'normal' | 'allowedTools')
+ * - SessionColor — visual differentiation color
+ * - OpenCodeConfig — OpenCode-specific settings (model, autoAllowTools, continueSession)
+ *
+ * Cross-domain relationships:
+ * - SessionState.respawnConfig embeds RespawnConfig (respawn domain)
+ * - SessionState.id is referenced by: RalphSessionState.sessionId (ralph),
+ *   RunSummary.sessionId (run-summary), ActiveBashTool.sessionId (tools),
+ *   TeamConfig.leadSessionId (teams), RespawnCycleMetrics.sessionId (respawn),
+ *   TaskState.assignedSessionId (task)
+ *
+ * Persisted to `~/.codeman/state.json`. Served at `GET /api/sessions` and
+ * `GET /api/sessions/:id`.
+ */
+import type { RespawnConfig } from './respawn.js';
+/** Status of a Claude session */
+export type SessionStatus = 'idle' | 'busy' | 'stopped' | 'error';
+/**
+ * Claude CLI startup permission mode.
+ * - `'dangerously-skip-permissions'`: Bypass all permission prompts (default)
+ * - `'normal'`: Standard mode with permission prompts
+ * - `'allowedTools'`: Only allow specific tools (requires allowedTools list)
+ */
+export type ClaudeMode = 'dangerously-skip-permissions' | 'normal' | 'allowedTools';
+/** Session mode: which CLI backend a session runs */
+export type SessionMode = 'claude' | 'shell' | 'opencode';
+/** OpenCode session configuration */
+export interface OpenCodeConfig {
+    /** Model identifier (e.g., "anthropic/claude-sonnet-4-5", "openai/gpt-5.2", "ollama/codellama") */
+    model?: string;
+    /** Whether to auto-allow all tool executions (sets permission.* = allow) */
+    autoAllowTools?: boolean;
+    /** Session ID to continue from */
+    continueSession?: string;
+    /** Whether to fork when continuing (branch the conversation) */
+    forkSession?: boolean;
+    /** Custom inline config JSON (passed via OPENCODE_CONFIG_CONTENT) */
+    configContent?: string;
+}
+/**
+ * Configuration for creating a new session
+ */
+export interface SessionConfig {
+    /** Unique session identifier */
+    id: string;
+    /** Working directory for the session */
+    workingDir: string;
+    /** Timestamp when session was created */
+    createdAt: number;
+}
+/**
+ * Available session colors for visual differentiation
+ */
+export type SessionColor = 'default' | 'red' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink';
+/**
+ * Current state of a session
+ */
+export interface SessionState {
+    /** Unique session identifier */
+    id: string;
+    /** Process ID of the PTY process, null if not running */
+    pid: number | null;
+    /** Current session status */
+    status: SessionStatus;
+    /** Working directory path */
+    workingDir: string;
+    /** ID of currently assigned task, null if none */
+    currentTaskId: string | null;
+    /** Timestamp when session was created */
+    createdAt: number;
+    /** Timestamp of last activity */
+    lastActivityAt: number;
+    /** Session display name */
+    name?: string;
+    /** Session mode */
+    mode?: SessionMode;
+    /** Auto-clear enabled */
+    autoClearEnabled?: boolean;
+    /** Auto-clear token threshold */
+    autoClearThreshold?: number;
+    /** Auto-compact enabled */
+    autoCompactEnabled?: boolean;
+    /** Auto-compact token threshold */
+    autoCompactThreshold?: number;
+    /** Auto-compact prompt */
+    autoCompactPrompt?: string;
+    /** Image watcher enabled for this session */
+    imageWatcherEnabled?: boolean;
+    /** Total cost in USD */
+    totalCost?: number;
+    /** Input tokens used */
+    inputTokens?: number;
+    /** Output tokens used */
+    outputTokens?: number;
+    /** Whether respawn controller is currently enabled/running */
+    respawnEnabled?: boolean;
+    /** Respawn controller config (if enabled) */
+    respawnConfig?: RespawnConfig & {
+        durationMinutes?: number;
+    };
+    /** Ralph / Todo tracker enabled */
+    ralphEnabled?: boolean;
+    /** Ralph auto-enable disabled (user explicitly turned off Ralph) */
+    ralphAutoEnableDisabled?: boolean;
+    /** Ralph completion phrase (if set) */
+    ralphCompletionPhrase?: string;
+    /** Parent agent ID if this session is a spawned agent */
+    parentAgentId?: string;
+    /** Child agent IDs spawned by this session */
+    childAgentIds?: string[];
+    /** Nice priority enabled */
+    niceEnabled?: boolean;
+    /** Nice value (-20 to 19) */
+    niceValue?: number;
+    /** User-assigned color for visual differentiation */
+    color?: SessionColor;
+    /** Flicker filter enabled (buffers output after screen clears) */
+    flickerFilterEnabled?: boolean;
+    /** Claude Code CLI version (parsed from terminal, e.g., "2.1.27") */
+    cliVersion?: string;
+    /** Claude model in use (parsed from terminal, e.g., "Opus 4.5") */
+    cliModel?: string;
+    /** Account type (parsed from terminal, e.g., "Claude Max", "API") */
+    cliAccountType?: string;
+    /** Latest CLI version available (parsed from version check) */
+    cliLatestVersion?: string;
+    /** OpenCode-specific configuration (only for mode === 'opencode') */
+    openCodeConfig?: OpenCodeConfig;
+}
+/**
+ * Output captured from a session
+ */
+export interface SessionOutput {
+    /** Standard output content */
+    stdout: string;
+    /** Standard error content */
+    stderr: string;
+    /** Exit code of the process, null if still running */
+    exitCode: number | null;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/types/session.d.ts.map

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

package/dist/types/session.js

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Session type definitions.
+ *
+ * Core domain type — SessionState is the primary entity in the system.
+ *
+ * Key exports:
+ * - SessionState — full session state (status, tokens, respawn, ralph, CLI metadata)
+ * - SessionConfig — creation-time config (id, workingDir, createdAt)
+ * - SessionOutput — captured stdout/stderr/exitCode
+ * - SessionStatus — 'idle' | 'busy' | 'stopped' | 'error'
+ * - SessionMode — 'claude' | 'shell' | 'opencode' (which CLI backend)
+ * - ClaudeMode — CLI permission mode ('dangerously-skip-permissions' | 'normal' | 'allowedTools')
+ * - SessionColor — visual differentiation color
+ * - OpenCodeConfig — OpenCode-specific settings (model, autoAllowTools, continueSession)
+ *
+ * Cross-domain relationships:
+ * - SessionState.respawnConfig embeds RespawnConfig (respawn domain)
+ * - SessionState.id is referenced by: RalphSessionState.sessionId (ralph),
+ *   RunSummary.sessionId (run-summary), ActiveBashTool.sessionId (tools),
+ *   TeamConfig.leadSessionId (teams), RespawnCycleMetrics.sessionId (respawn),
+ *   TaskState.assignedSessionId (task)
+ *
+ * Persisted to `~/.codeman/state.json`. Served at `GET /api/sessions` and
+ * `GET /api/sessions/:id`.
+ */
+export {};
+//# sourceMappingURL=session.js.map

package/dist/types/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/types/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}