vibepulse 0.1.0 → 0.1.2

package/README.md

@@ -37,25 +37,19 @@ Real-time dashboard for monitoring and managing OpenCode sessions.
 
 ## Getting Started
 
-### Quick Start (npx)
-
-```bash
-# Run directly without installing
-npx vibepulse
-
-# Or specify a custom port
-PORT=8080 npx vibepulse
-```
-
-Open [http://localhost:3456](http://localhost:3456)
-
 ### Development
 
+Clone and run from source:
+
 ```bash
+# Clone the repository
+git clone https://github.com/ChatTreeNet/VibePulse.git
+cd VibePulse
+
 # Install dependencies
 npm install
 
-# Make sure OpenCode is running locally, then:
+# Start development server
 npm run dev
 
 # Or specify a custom port

package/bin/vibepulse.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+/* eslint-disable @typescript-eslint/no-require-imports */
 
 const { spawn } = require('child_process');
 const path = require('path');

package/dist/index.js

@@ -48,7 +48,7 @@ async function readConfig(configPath = CONFIG_PATH) {
     const content = await (0, import_promises.readFile)(configPath, "utf-8");
     const config = (0, import_comment_json.parse)(content, null, false);
     return config;
-  } catch (error) {
+  } catch {
     return {};
   }
 }

package/dist/index.mjs

@@ -18,7 +18,7 @@ async function readConfig(configPath = CONFIG_PATH) {
     const content = await readFile(configPath, "utf-8");
     const config = parse(content, null, false);
     return config;
-  } catch (error) {
+  } catch {
     return {};
   }
 }

package/docs/session-status-detection.md

@@ -0,0 +1,258 @@
+# VibePulse Session Status Detection
+
+## Overview
+
+VibePulse uses a multi-layer detection mechanism to determine the real-time status of OpenCode sessions (idle/busy/retry). Since OpenCode's native status reporting is sparse and delayed, the system combines multiple signals to improve status accuracy.
+
+---
+
+## Core Concepts
+
+### Status Definitions
+
+| Status | Meaning | Column |
+|--------|---------|--------|
+| `idle` | Idle / Completed | Idle Column |
+| `busy` | Actively Running | Busy Column |
+| `retry` | Waiting for User Input / Retry | Needs Attention Column |
+
+---
+
+## Detection Architecture
+
+```mermaid
+flowchart TB
+    subgraph Input["Input Signal Layer"]
+        A1["OpenCode /session/status\nSparse, often empty"]
+        A2["Message Part Status\nrunning/completed/waiting"]
+        A3["Session Metadata\nupdated/created timestamps"]
+    end
+    
+    subgraph Process["Status Processing Layer"]
+        B1["Part Status Analysis"]
+        B2["Sticky State Management\n25s one-way buffer"]
+        B3["Child Session Cascade"]
+    end
+    
+    subgraph Output["Output Layer"]
+        C1["realTimeStatus"]
+        C2["waitingForUser"]
+        C3["Kanban Column Assignment"]
+    end
+    
+    A1 --> B1
+    A2 --> B1
+    A3 --> B2
+    B1 --> B2
+    B2 --> C1
+    B2 --> B3
+    B3 --> C2
+    C1 --> C3
+    C2 --> C3
+```
+
+---
+
+## Key Detection Mechanisms
+
+### 1. Part Status Analysis
+
+Extracts part status from recent session messages to determine activity:
+
+```mermaid
+flowchart TD
+    A["Fetch last 8 messages"] --> B{"Any running part?"}
+    B -->|Yes| C["Status = busy"]
+    B -->|No| D{"Any waiting part?"}
+    D -->|Yes| E["Status = retry\nwaitingForUser = true"]
+    D -->|No| F{"All parts completed?"}
+    F -->|Yes| G["Likely idle"]
+    F -->|No| H["Unknown state"]
+```
+
+**Key Limitation**: Only checks the last 8 messages. Tasks with long periods of no output are misclassified as completed.
+
+---
+
+### 2. One-Way Sticky State (Core Mechanism)
+
+Prevents status jitter using a **one-way buffering strategy**:
+
+```mermaid
+flowchart LR
+    subgraph IdleToBusy["idle → busy"]
+        A1["Detected busy"] --> A2["Immediate effect"]
+        A2 --> A3["Update lastBusyAt = now"]
+    end
+    
+    subgraph BusyToIdle["busy → idle"]
+        B1["Detected idle"] --> B2{"lastBusyAt\nwithin 25s?"}
+        B2 -->|Yes| B3["Keep busy\n(sticky)"]
+        B2 -->|No| B4["Actually become idle"]
+    end
+```
+
+**Design Rationale**:
+- `idle → busy`: **Immediate effect** (once busy is detected, it's truly running)
+- `busy → idle`: **25-second buffer** (prevents misclassification from brief state loss)
+
+---
+
+### 3. Child Session Cascade
+
+Parent session status is influenced by child sessions:
+
+```mermaid
+flowchart TB
+    subgraph Parent["Parent Session"]
+        P1["realTimeStatus: idle"]
+        P2["But has child sessions"]
+    end
+    
+    subgraph Children["Child Session States"]
+        C1["Child 1: busy"]
+        C2["Child 2: idle"]
+        C3["Child 3: retry"]
+    end
+    
+    P1 --> D{"Any child session active?"}
+    C1 --> D
+    C2 --> D
+    C3 --> D
+    
+    D -->|Yes| E["effectiveStatus = busy\nDisplay in Busy Column"]
+    D -->|No| F["effectiveStatus = idle\nDisplay in Idle Column"]
+```
+
+---
+
+## Complete State Transition Flow
+
+```mermaid
+sequenceDiagram
+    participant OC as OpenCode
+    participant API as /api/sessions
+    participant Sticky as Sticky State Manager
+    participant UI as Kanban UI
+    
+    Note over OC,UI: Scenario: Long-running task
+    
+    OC->>OC: Task starts (busy)
+    OC->>API: /session/status = busy
+    API->>Sticky: Update lastBusyAt
+    Sticky->>UI: Display busy
+    
+    Note over OC,UI: 10 seconds later, OpenCode stops sending status
+    
+    OC->>API: /session/status = null (sparse)
+    API->>Sticky: Query lastBusyAt
+    Sticky-->>Sticky: now - lastBusyAt = 10s < 25s
+    Sticky->>UI: **Keep busy** (sticky)
+    
+    Note over OC,UI: 30 seconds later
+    
+    API->>Sticky: Query lastBusyAt
+    Sticky-->>Sticky: now - lastBusyAt = 30s > 25s
+    Sticky->>UI: **Become idle**
+```
+
+---
+
+## Detection Limitations (Shortcomings)
+
+### Root Cause: Unreliable Signal Source
+
+```mermaid
+flowchart TB
+    subgraph RootCause["Root Cause: Insufficient OpenCode Signals"]
+        R1["No heartbeat mechanism\nCannot prove 'I am computing'"]
+        R2["Sparse status reporting\n/session/status often empty"]
+        R3["Discrete part status\nOnly running/completed, no progress"]
+    end
+    
+    subgraph Workarounds["Current Workarounds"]
+        W1["Time buffer (25s sticky)"]
+        W2["Message history inference (8 messages)"]
+        W3["Child session cascade"]
+    end
+    
+    RootCause --> Workarounds
+```
+
+### Specific Shortcomings
+
+| Shortcoming | Impact Scenario | User Experience |
+|-------------|-----------------|-----------------|
+| **1. Shallow message sampling** | Long computation without output | Misclassified as idle, user thinks task finished |
+| **2. Fixed time window** | One-size-fits-all approach | 25s may be too short for some tasks, too long for others |
+| **3. No CPU/IO monitoring** | Process hang or deadlock | Continuously shows busy, user waits in vain |
+| **4. Cannot detect deep subtask nesting** | Nested agent calls | Grandchild task status not trackable |
+| **5. Network jitter sensitive** | Brief disconnection | May trigger unnecessary stale state |
+| **6. Audio-visual out of sync** | Rapid status switching | Sound plays before/after card movement, disjointed experience |
+
+### Misclassification Example
+
+```mermaid
+sequenceDiagram
+    participant User as User
+    participant UI as VibePulse Kanban
+    participant Task as Background Task
+    
+    Note over User,Task: Scenario: Data analysis task running
+    
+    User->>UI: Check kanban
+    UI->>Task: Query status
+    Task-->>UI: busy (second 1)
+    UI-->>User: Display Busy ✓
+    
+    Note over User,Task: Task continues, but no new messages
+    
+    Task->>Task: Continuous computation (no output)
+    
+    Note over User,Task: After 25 seconds...
+    
+    UI->>Task: Query status
+    Task-->>UI: No status / completed parts
+    UI-->>UI: Sticky window expired
+    UI-->>User: Display Idle ✗ (Misclassification!)
+    
+    User->>User: Confused: Did the task finish?
+```
+
+### Improvement Directions (Not Implemented)
+
+| Improvement | Difficulty | Impact | Priority |
+|-------------|------------|--------|----------|
+| Increase message sampling depth (50 messages) | Low | Reduce misclassification | P2 |
+| Process-level CPU monitoring | Medium | Detect deadlocks | P1 |
+| Adaptive time window (by task type) | Medium | Precise judgment | P3 |
+| MCP Progress Token integration | High | Accurate progress | P1 (requires OpenCode support) |
+| Heartbeat keepalive mechanism | High | Real-time status | P2 (requires protocol change) |
+
+---
+
+## Key Time Parameters
+
+| Parameter | Value | Purpose |
+|-----------|-------|---------|
+| `STATUS_STICKY_BUSY_WINDOW_MS` | 25 seconds | Buffer window for busy → idle transition |
+| `CHILD_ACTIVE_WINDOW_MS` | 30 minutes | Child session activity determination window |
+| `CHILD_UNKNOWN_STATE_BUSY_WINDOW_MS` | 2 minutes | Busy assumption for unknown states |
+| `STALL_DETECTION_WINDOW_MS` | 30 seconds | Stall detection (if updated time is within this window) |
+| `STATUS_STICKY_RETENTION_MS` | 24 hours | Sticky state memory retention time |
+
+---
+
+## Data Flow Summary
+
+```mermaid
+flowchart LR
+    A["OpenCode\nTrue State"] -->|Sparse signals| B("VibePulse\nMulti-layer detection")
+    B -->|Sticky buffering| C["Stable State"]
+    C -->|transform| D["Kanban Cards"]
+    D -->|Animation| E["UI Column Movement"]
+    
+    F["Sound Alert"] -.->|Delayed 250ms| E
+```
+
+**Core Design Philosophy**: Due to unreliable upstream (OpenCode) signals, the system provides **good enough** stability through **time buffering** and **multi-layer inference**, rather than absolute precision.

package/next.config.ts

@@ -0,0 +1,11 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  // Use a less common port to avoid conflicts
+  // Can be overridden with PORT env var
+  ...(process.env.PORT && {
+    // Next.js doesn't support port in config, use env var instead
+  }),
+};
+
+export default nextConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibepulse",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "Real-time dashboard for monitoring and managing OpenCode sessions",
   "repository": {
@@ -12,6 +12,19 @@
   "files": [
     "dist",
     "bin",
+    "src",
+    "app",
+    "public",
+    "components",
+    "lib",
+    "hooks",
+    "types",
+    "docs",
+    "next.config.ts",
+    "tsconfig.json",
+    "tsconfig.lib.json",
+    "tailwind.config.ts",
+    "postcss.config.mjs",
     "README.md",
     "LICENSE"
   ],
@@ -22,16 +35,6 @@
       "require": "./dist/index.cjs"
     }
   },
-  "peerDependencies": {
-    "next": ">=14.0.0",
-    "react": ">=18.0.0",
-    "react-dom": ">=18.0.0"
-  },
-  "peerDependenciesMeta": {
-    "next": {
-      "optional": true
-    }
-  },
   "scripts": {
     "dev": "next dev -p 3456",
     "build": "next build",
@@ -56,6 +59,9 @@
     "clsx": "^2.1.1",
     "comment-json": "^4.6.2",
     "lucide-react": "^0.575.0",
+    "next": "^16.1.6",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "react-hook-form": "^7.71.2",
     "tailwind-merge": "^3.5.0"
   },

package/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/public/file.svg

@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

package/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

package/public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

package/public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

package/public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>