selfhostyourtech/reflector
2
0
Fork 0
mirror of https://github.com/Monadical-SAS/reflector.git synced 2026-02-04 18:06:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

cleanup

Browse Source
This commit is contained in:
Igor Loskutov
2026-01-13 12:46:03 -05:00
parent 3652de9fca
commit b84fd1fc24
39 changed files with 0 additions and 10648 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.flow/bin/flowctl
View File

@@ -1,4 +0,0 @@
#!/bin/bash
# flowctl wrapper - invokes flowctl.py from the same directory
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
exec python3 "$SCRIPT_DIR/flowctl.py" "$@"

3960
.flow/bin/flowctl.py
View File

File diff suppressed because it is too large Load Diff

1
.flow/config.json
View File

@@ -1 +0,0 @@
{"memory":{"enabled":false}}

13
.flow/epics/fn-1.json
View File

@@ -1,13 +0,0 @@
{
"branch_name": "fn-1",
"created_at": "2026-01-12T22:40:52.831445Z",
"depends_on_epics": [],
"id": "fn-1",
"next_task": 1,
"plan_review_status": "unknown",
"plan_reviewed_at": null,
"spec_path": ".flow/specs/fn-1.md",
"status": "open",
"title": "Transcript Chat Assistant (POC)",
"updated_at": "2026-01-12T22:40:52.831630Z"
}

1
.flow/meta.json
View File

@@ -1 +0,0 @@
{"schema_version": 2, "next_epic": 1, "setup_version": "0.6.1", "setup_date": "2026-01-12"}

52
.flow/specs/fn-1.1.md
View File

@@ -1,52 +0,0 @@
# Task 1: WebSocket Endpoint Skeleton
**File:** `server/reflector/views/transcripts_chat.py`
**Lines:** ~30
**Dependencies:** None
## Objective
Create basic WebSocket endpoint with auth and connection handling.
## Implementation
```python
from typing import Optional
from fastapi import APIRouter, Depends, WebSocket, WebSocketDisconnect
import reflector.auth as auth
from reflector.db.transcripts import transcripts_controller
router = APIRouter()
@router.websocket("/transcripts/{transcript_id}/chat")
async def transcript_chat_websocket(
transcript_id: str,
websocket: WebSocket,
user: Optional[auth.UserInfo] = Depends(auth.current_user_optional),
):
# 1. Auth check
user_id = user["sub"] if user else None
transcript = await transcripts_controller.get_by_id_for_http(
transcript_id, user_id
)
# 2. Accept connection
await websocket.accept()
try:
# 3. Basic message loop (stub)
while True:
data = await websocket.receive_json()
await websocket.send_json({"type": "echo", "data": data})
except WebSocketDisconnect:
pass
```
## Validation
- [ ] Endpoint accessible at `ws://localhost:1250/v1/transcripts/{id}/chat`
- [ ] Auth check executes (404 if transcript not found)
- [ ] Connection accepts
- [ ] Echo messages back to client
- [ ] Disconnect handled gracefully
## Notes
- Test with `websocat` or browser WebSocket client
- Don't add LLM yet, just echo

43
.flow/specs/fn-1.2.md
View File

@@ -1,43 +0,0 @@
# Task 2: WebVTT Context Generation
**File:** `server/reflector/views/transcripts_chat.py` (modify)
**Lines:** ~15
**Dependencies:** Task 1
## Objective
Generate WebVTT transcript context on connection.
## Implementation
```python
from reflector.utils.transcript_formats import topics_to_webvtt_named
from reflector.views.transcripts import _get_is_multitrack
# Add after websocket.accept():
# Get WebVTT context
is_multitrack = await _get_is_multitrack(transcript)
webvtt = topics_to_webvtt_named(
transcript.topics,
transcript.participants,
is_multitrack
)
# Truncate if needed
webvtt_truncated = webvtt[:15000] if len(webvtt) > 15000 else webvtt
# Send to client for verification
await websocket.send_json({
"type": "context",
"webvtt": webvtt_truncated,
"truncated": len(webvtt) > 15000
})
```
## Validation
- [ ] WebVTT generated on connection
- [ ] Truncated to 15k chars if needed
- [ ] Client receives context message
- [ ] Format matches WebVTT spec (timestamps, speaker names)
## Notes
- Log if truncation occurs
- Keep echo functionality for testing

67
.flow/specs/fn-1.3.md
View File

@@ -1,67 +0,0 @@
# Task 3: LLM Streaming Integration
**File:** `server/reflector/views/transcripts_chat.py` (modify)
**Lines:** ~35
**Dependencies:** Task 2
## Objective
Integrate LLM streaming with conversation management.
## Implementation
```python
from llama_index.core import Settings
from reflector.llm import LLM
from reflector.settings import settings
# After WebVTT generation:
# Configure LLM
llm = LLM(settings=settings, temperature=0.7)
# System message
system_msg = f"""You are analyzing this meeting transcript (WebVTT):
{webvtt_truncated}
Answer questions about content, speakers, timeline. Include timestamps when relevant."""
# Conversation history
conversation_history = [{"role": "system", "content": system_msg}]
# Replace echo loop with:
try:
while True:
data = await websocket.receive_json()
if data["type"] != "message":
continue
# Add user message
user_msg = {"role": "user", "content": data["text"]}
conversation_history.append(user_msg)
# Stream LLM response
assistant_msg = ""
async for chunk in Settings.llm.astream_chat(conversation_history):
token = chunk.delta
await websocket.send_json({"type": "token", "text": token})
assistant_msg += token
# Save assistant response
conversation_history.append({"role": "assistant", "content": assistant_msg})
await websocket.send_json({"type": "done"})
except WebSocketDisconnect:
pass
except Exception as e:
await websocket.send_json({"type": "error", "message": str(e)})
```
## Validation
- [ ] LLM responds to user messages
- [ ] Tokens stream incrementally
- [ ] Conversation history maintained
- [ ] `done` message sent after completion
- [ ] Errors caught and sent to client
## Notes
- Test with: "What was discussed?"
- Verify timestamps appear in responses

22
.flow/specs/fn-1.4.md
View File

@@ -1,22 +0,0 @@
# Task 4: Register WebSocket Route
**File:** `server/reflector/app.py` (modify)
**Lines:** ~3
**Dependencies:** Task 3
## Objective
Register chat router in FastAPI app.
## Implementation
```python
# Add import
from reflector.views.transcripts_chat import router as transcripts_chat_router
# Add to route registration section
app.include_router(transcripts_chat_router, prefix="/v1", tags=["transcripts"])
```
## Validation
- [ ] Route appears in OpenAPI docs at `/docs`
- [ ] WebSocket endpoint accessible from frontend
- [ ] No import errors

102
.flow/specs/fn-1.5.md
View File

@@ -1,102 +0,0 @@
# Task 5: Frontend WebSocket Hook
**File:** `www/app/(app)/transcripts/useTranscriptChat.ts`
**Lines:** ~60
**Dependencies:** Task 1 (protocol defined)
## Objective
Create React hook for WebSocket chat communication.
## Implementation
```typescript
import { useEffect, useState, useRef } from "react"
import { WEBSOCKET_URL } from "../../lib/apiClient"
type Message = {
id: string
role: "user" | "assistant"
text: string
timestamp: Date
}
export const useTranscriptChat = (transcriptId: string) => {
const [messages, setMessages] = useState<Message[]>([])
const [isStreaming, setIsStreaming] = useState(false)
const [currentStreamingText, setCurrentStreamingText] = useState("")
const wsRef = useRef<WebSocket | null>(null)
useEffect(() => {
const ws = new WebSocket(
`${WEBSOCKET_URL}/v1/transcripts/${transcriptId}/chat`
)
wsRef.current = ws
ws.onopen = () => console.log("Chat WebSocket connected")
ws.onmessage = (event) => {
const msg = JSON.parse(event.data)
switch (msg.type) {
case "token":
setIsStreaming(true)
setCurrentStreamingText((prev) => prev + msg.text)
break
case "done":
setMessages((prev) => [
...prev,
{
id: Date.now().toString(),
role: "assistant",
text: currentStreamingText,
timestamp: new Date(),
},
])
setCurrentStreamingText("")
setIsStreaming(false)
break
case "error":
console.error("Chat error:", msg.message)
setIsStreaming(false)
break
}
}
ws.onerror = (error) => console.error("WebSocket error:", error)
ws.onclose = () => console.log("Chat WebSocket closed")
return () => ws.close()
}, [transcriptId, currentStreamingText])
const sendMessage = (text: string) => {
if (!wsRef.current) return
setMessages((prev) => [
...prev,
{
id: Date.now().toString(),
role: "user",
text,
timestamp: new Date(),
},
])
wsRef.current.send(JSON.stringify({ type: "message", text }))
}
return { messages, sendMessage, isStreaming, currentStreamingText }
}
```
## Validation
- [ ] Hook connects to WebSocket
- [ ] Sends messages to server
- [ ] Receives streaming tokens
- [ ] Accumulates tokens into messages
- [ ] Handles done/error events
- [ ] Closes connection on unmount
## Notes
- Test with browser console first
- Verify message format matches backend protocol

124
.flow/specs/fn-1.6.md
View File

@@ -1,124 +0,0 @@
# Task 6: Chat Dialog Component
**File:** `www/app/(app)/transcripts/TranscriptChatModal.tsx`
**Lines:** ~90
**Dependencies:** Task 5 (hook interface)
## Objective
Create Chakra UI v3 Dialog component for chat interface.
## Implementation
```typescript
"use client"
import { useState } from "react"
import { Dialog, Box, Input, IconButton } from "@chakra-ui/react"
import { MessageCircle } from "lucide-react"
type Message = {
id: string
role: "user" | "assistant"
text: string
timestamp: Date
}
interface TranscriptChatModalProps {
open: boolean
onClose: () => void
messages: Message[]
sendMessage: (text: string) => void
isStreaming: boolean
currentStreamingText: string
}
export function TranscriptChatModal({
open,
onClose,
messages,
sendMessage,
isStreaming,
currentStreamingText,
}: TranscriptChatModalProps) {
const [input, setInput] = useState("")
const handleSend = () => {
if (!input.trim()) return
sendMessage(input)
setInput("")
}
return (
<Dialog.Root open={open} onOpenChange={(e) => !e.open && onClose()}>
<Dialog.Backdrop />
<Dialog.Positioner>
<Dialog.Content maxW="500px" h="600px">
<Dialog.Header>Transcript Chat</Dialog.Header>
<Dialog.Body overflowY="auto">
{messages.map((msg) => (
<Box
key={msg.id}
p={3}
mb={2}
bg={msg.role === "user" ? "blue.50" : "gray.50"}
borderRadius="md"
>
{msg.text}
</Box>
))}
{isStreaming && (
<Box p={3} bg="gray.50" borderRadius="md">
{currentStreamingText}
<Box as="span" className="animate-pulse">
▊
</Box>
</Box>
)}
</Dialog.Body>
<Dialog.Footer>
<Input
value={input}
onChange={(e) => setInput(e.target.value)}
onKeyDown={(e) => e.key === "Enter" && handleSend()}
placeholder="Ask about transcript..."
disabled={isStreaming}
/>
</Dialog.Footer>
</Dialog.Content>
</Dialog.Positioner>
</Dialog.Root>
)
}
export function TranscriptChatButton({ onClick }: { onClick: () => void }) {
return (
<IconButton
position="fixed"
bottom="24px"
right="24px"
onClick={onClick}
size="lg"
colorScheme="blue"
borderRadius="full"
aria-label="Open chat"
>
<MessageCircle />
</IconButton>
)
}
```
## Validation
- [ ] Dialog opens/closes correctly
- [ ] Messages display (user: blue, assistant: gray)
- [ ] Streaming text shows with cursor
- [ ] Input disabled during streaming
- [ ] Enter key sends message
- [ ] Dialog scrolls with content
- [ ] Floating button positioned correctly
## Notes
- Test with mock data before connecting hook
- Verify Chakra v3 Dialog.Root API

54
.flow/specs/fn-1.7.md
View File

@@ -1,54 +0,0 @@
# Task 7: Integrate into Transcript Page
**File:** `www/app/(app)/transcripts/[transcriptId]/page.tsx` (modify)
**Lines:** ~15
**Dependencies:** Task 5, Task 6
## Objective
Add chat components to transcript detail page.
## Implementation
```typescript
// Add imports
import { useDisclosure } from "@chakra-ui/react"
import {
TranscriptChatModal,
TranscriptChatButton,
} from "../TranscriptChatModal"
import { useTranscriptChat } from "../useTranscriptChat"
// Inside component:
export default function TranscriptDetails(details: TranscriptDetails) {
const params = use(details.params)
const transcriptId = params.transcriptId
// Add chat state
const { open, onOpen, onClose } = useDisclosure()
const chat = useTranscriptChat(transcriptId)
return (
<>
{/* Existing Grid with transcript content */}
<Grid templateColumns="1fr" templateRows="auto minmax(0, 1fr)" /* ... */>
{/* ... existing content ... */}
</Grid>
{/* Chat interface */}
<TranscriptChatModal open={open} onClose={onClose} {...chat} />
<TranscriptChatButton onClick={onOpen} />
</>
)
}
```
## Validation
- [ ] Button appears on transcript page
- [ ] Clicking button opens dialog
- [ ] Chat works end-to-end
- [ ] Dialog closes properly
- [ ] No layout conflicts with existing UI
- [ ] Button doesn't overlap other elements
## Notes
- Test on different transcript pages
- Verify z-index for button and dialog

47
.flow/specs/fn-1.8.md
View File

@@ -1,47 +0,0 @@
# Task 8: End-to-End Testing
**File:** N/A (testing)
**Lines:** 0
**Dependencies:** All tasks (1-7)
## Objective
Validate complete feature functionality.
## Test Scenarios
### 1. Basic Flow
- [ ] Navigate to transcript page
- [ ] Click floating button
- [ ] Dialog opens with "Transcript Chat" header
- [ ] Type "What was discussed?"
- [ ] Press Enter
- [ ] Streaming response appears token-by-token
- [ ] Response completes with relevant content
- [ ] Ask follow-up question
- [ ] Conversation context maintained
### 2. Edge Cases
- [ ] Empty message (doesn't send)
- [ ] Very long transcript (>15k chars truncated)
- [ ] Network disconnect (graceful error)
- [ ] Multiple rapid messages (queued correctly)
- [ ] Close dialog mid-stream (conversation cleared)
- [ ] Reopen dialog (fresh conversation)
### 3. Auth
- [ ] Works with logged-in user
- [ ] Works with anonymous user
- [ ] Private transcript blocked for wrong user
### 4. UI/UX
- [ ] Button doesn't cover other UI elements
- [ ] Dialog scrolls properly
- [ ] Streaming cursor visible
- [ ] Input disabled during streaming
- [ ] Messages clearly distinguished (user vs assistant)
## Bugs to Watch
- WebSocket connection leaks (check browser devtools)
- Streaming text accumulation bugs
- Race conditions on rapid messages
- Memory leaks from conversation history

439
.flow/specs/fn-1.md
View File

@@ -1,439 +0,0 @@
# PRD: Transcript Chat Assistant (POC)
## Research Complete
**Backend Infrastructure:**
- LLM configured: `reflector/llm.py` using llama-index's `OpenAILike`
- Streaming support: `Settings.llm.astream_chat()` available (configured by LLM class)
- WebSocket infrastructure: Redis pub/sub via `ws_manager`
- Existing pattern: `/v1/transcripts/{transcript_id}/events` WebSocket (broadcast-only)
**Frontend Infrastructure:**
- `useWebSockets` hook pattern established
- Chakra UI v3 with Dialog.Root API
- lucide-react icons available
**Decision: Use existing WebSocket + custom chat UI**
---
## Architecture
```
Frontend Backend (FastAPI)
┌──────────────────┐ ┌────────────────────────────┐
│ Transcript Page │ │ /v1/transcripts/{id}/chat │
│ │ │ │
│ ┌──────────────┐ │ │ WebSocket Endpoint │
│ │ Chat Dialog │ │◄──WebSocket│ (bidirectional) │
│ │ │ │────────────┤ 1. Auth check │
│ │ - Messages │ │ send msg │ 2. Get WebVTT transcript │
│ │ - Input │ │ │ 3. Build conversation │
│ │ - Streaming │ │◄───────────┤ 4. Call astream_chat() │
│ └──────────────┘ │ stream │ 5. Stream tokens via WS │
│ useTranscriptChat│ response │ │
└──────────────────┘ │ ┌────────────────────────┐ │
│ │ LLM (llama-index) │ │
│ │ Settings.llm │ │
│ │ astream_chat() │ │
│ └────────────────────────┘ │
│ │
│ Existing: │
│ - topics_to_webvtt_named() │
└────────────────────────────┘
```
**Note:** This WebSocket is bidirectional (client→server messages) unlike existing broadcast-only pattern (`/events` endpoint).
---
## Components
### Backend
**1. WebSocket Endpoint** (`server/reflector/views/transcripts_chat.py`)
```python
@router.websocket("/transcripts/{transcript_id}/chat")
async def transcript_chat_websocket(
transcript_id: str,
websocket: WebSocket,
user: Optional[auth.UserInfo] = Depends(auth.current_user_optional),
):
# 1. Auth check
user_id = user["sub"] if user else None
transcript = await transcripts_controller.get_by_id_for_http(transcript_id, user_id)
# 2. Accept WebSocket
await websocket.accept()
# 3. Get WebVTT context
webvtt = topics_to_webvtt_named(
transcript.topics,
transcript.participants,
await _get_is_multitrack(transcript)
)
# 4. Configure LLM (sets up Settings.llm with session tracking)
llm = LLM(settings=settings, temperature=0.7)
# 5. System message
system_msg = f"""You are analyzing this meeting transcript (WebVTT):
{webvtt[:15000]} # Truncate if needed
Answer questions about content, speakers, timeline. Include timestamps when relevant."""
# 6. Conversation loop
conversation_history = [{"role": "system", "content": system_msg}]
try:
while True:
# Receive user message
data = await websocket.receive_json()
if data["type"] != "message":
continue
user_msg = {"role": "user", "content": data["text"]}
conversation_history.append(user_msg)
# Stream LLM response
assistant_msg = ""
async for chunk in Settings.llm.astream_chat(conversation_history):
token = chunk.delta
await websocket.send_json({"type": "token", "text": token})
assistant_msg += token
conversation_history.append({"role": "assistant", "content": assistant_msg})
await websocket.send_json({"type": "done"})
except WebSocketDisconnect:
pass
except Exception as e:
await websocket.send_json({"type": "error", "message": str(e)})
```
**Message Protocol:**
```typescript
// Client → Server
{type: "message", text: "What was discussed?"}
// Server → Client (streaming)
{type: "token", text: "At "}
{type: "token", text: "01:23"}
...
{type: "done"}
{type: "error", message: "..."} // on errors
```
### Frontend
**2. Chat Hook** (`www/app/(app)/transcripts/useTranscriptChat.ts`)
```typescript
export const useTranscriptChat = (transcriptId: string) => {
const [messages, setMessages] = useState<Message[]>([])
const [isStreaming, setIsStreaming] = useState(false)
const [currentStreamingText, setCurrentStreamingText] = useState("")
const wsRef = useRef<WebSocket | null>(null)
useEffect(() => {
const ws = new WebSocket(`${WEBSOCKET_URL}/v1/transcripts/${transcriptId}/chat`)
wsRef.current = ws
ws.onopen = () => console.log("Chat WebSocket connected")
ws.onmessage = (event) => {
const msg = JSON.parse(event.data)
switch (msg.type) {
case "token":
setIsStreaming(true)
setCurrentStreamingText(prev => prev + msg.text)
break
case "done":
setMessages(prev => [...prev, {
id: Date.now().toString(),
role: "assistant",
text: currentStreamingText,
timestamp: new Date()
}])
setCurrentStreamingText("")
setIsStreaming(false)
break
case "error":
console.error("Chat error:", msg.message)
setIsStreaming(false)
break
}
}
ws.onerror = (error) => console.error("WebSocket error:", error)
ws.onclose = () => console.log("Chat WebSocket closed")
return () => ws.close()
}, [transcriptId])
const sendMessage = (text: string) => {
if (!wsRef.current) return
setMessages(prev => [...prev, {
id: Date.now().toString(),
role: "user",
text,
timestamp: new Date()
}])
wsRef.current.send(JSON.stringify({type: "message", text}))
}
return {messages, sendMessage, isStreaming, currentStreamingText}
}
```
**3. Chat Dialog** (`www/app/(app)/transcripts/TranscriptChatModal.tsx`)
```tsx
import { Dialog, Box, Input, IconButton } from "@chakra-ui/react"
import { MessageCircle } from "lucide-react"
interface TranscriptChatModalProps {
open: boolean
onClose: () => void
messages: Message[]
sendMessage: (text: string) => void
isStreaming: boolean
currentStreamingText: string
}
export function TranscriptChatModal({
open,
onClose,
messages,
sendMessage,
isStreaming,
currentStreamingText
}: TranscriptChatModalProps) {
const [input, setInput] = useState("")
const handleSend = () => {
if (!input.trim()) return
sendMessage(input)
setInput("")
}
return (
<Dialog.Root open={open} onOpenChange={(e) => !e.open && onClose()}>
<Dialog.Backdrop />
<Dialog.Positioner>
<Dialog.Content maxW="500px" h="600px">
<Dialog.Header>Transcript Chat</Dialog.Header>
<Dialog.Body overflowY="auto">
{messages.map(msg => (
<Box
key={msg.id}
p={3}
mb={2}
bg={msg.role === "user" ? "blue.50" : "gray.50"}
borderRadius="md"
>
{msg.text}
</Box>
))}
{isStreaming && (
<Box p={3} bg="gray.50" borderRadius="md">
{currentStreamingText}
<Box as="span" className="animate-pulse">▊</Box>
</Box>
)}
</Dialog.Body>
<Dialog.Footer>
<Input
value={input}
onChange={(e) => setInput(e.target.value)}
onKeyDown={(e) => e.key === "Enter" && handleSend()}
placeholder="Ask about transcript..."
disabled={isStreaming}
/>
</Dialog.Footer>
</Dialog.Content>
</Dialog.Positioner>
</Dialog.Root>
)
}
// Floating button
export function TranscriptChatButton({ onClick }: { onClick: () => void }) {
return (
<IconButton
position="fixed"
bottom="24px"
right="24px"
onClick={onClick}
size="lg"
colorScheme="blue"
borderRadius="full"
aria-label="Open chat"
>
<MessageCircle />
</IconButton>
)
}
```
**4. Integration** (Modify `/transcripts/[transcriptId]/page.tsx`)
```tsx
import { useDisclosure } from "@chakra-ui/react"
import { TranscriptChatModal, TranscriptChatButton } from "../TranscriptChatModal"
import { useTranscriptChat } from "../useTranscriptChat"
export default function TranscriptDetails(details: TranscriptDetails) {
const params = use(details.params)
const transcriptId = params.transcriptId
const { open, onOpen, onClose } = useDisclosure()
const chat = useTranscriptChat(transcriptId)
return (
<>
{/* Existing transcript UI */}
<Grid templateColumns="1fr" /* ... */>
{/* ... existing content ... */}
</Grid>
{/* Chat interface */}
<TranscriptChatModal
open={open}
onClose={onClose}
{...chat}
/>
<TranscriptChatButton onClick={onOpen} />
</>
)
}
```
---
## Data Structures
```typescript
type Message = {
id: string
role: "user" | "assistant"
text: string
timestamp: Date
}
```
---
## API Specifications
### WebSocket Endpoint
**URL:** `ws://localhost:1250/v1/transcripts/{transcript_id}/chat`
**Auth:** Optional user (same as existing endpoints)
**Client → Server:**
```json
{"type": "message", "text": "What was discussed?"}
```
**Server → Client:**
```json
{"type": "token", "text": "chunk"}
{"type": "done"}
{"type": "error", "message": "error text"}
```
---
## Implementation Notes
**LLM Integration:**
- Instantiate `LLM()` to configure `Settings.llm` with session tracking
- Use `Settings.llm.astream_chat()` directly for streaming
- Chunks have `.delta` property with token text
**WebVTT Context:**
- Reuse `topics_to_webvtt_named()` utility
- Truncate to ~15k chars if needed (known limitation for POC)
- Include in system message
**Conversation State:**
- Store in-memory in WebSocket handler (ephemeral)
- Clear on disconnect
- No persistence (out of scope)
**Error Handling:**
- Basic try/catch with error message to client
- Log errors server-side
---
## File Structure
```
server/reflector/views/
└── transcripts_chat.py # New: ~80 lines
www/app/(app)/transcripts/
├── [transcriptId]/
│ └── page.tsx # Modified: +10 lines
├── useTranscriptChat.ts # New: ~60 lines
└── TranscriptChatModal.tsx # New: ~80 lines
```
**Total:** ~230 lines of code
---
## Dependencies
**Backend:** None (all existing)
**Frontend:** None (Chakra UI + lucide-react already installed)
---
## Out of Scope (POC)
- ❌ Message persistence/history
- ❌ Context window optimization
- ❌ Sentence buffering (token-by-token is fine)
- ❌ Rate limiting beyond auth
- ❌ Tool calling
- ❌ RAG/vector search
**Known Limitations:**
- Long transcripts (>15k chars) will be truncated
- Conversation lost on disconnect
- No error recovery/retry
---
## Acceptance Criteria
- [ ] Floating button on transcript page
- [ ] Click opens dialog with chat interface
- [ ] Send message, receive streaming response
- [ ] LLM has WebVTT transcript context
- [ ] Auth works (optional user)
- [ ] Dialog closes, conversation cleared
- [ ] Works with configured OpenAI-compatible LLM
---
## References
- [LlamaIndex Streaming](https://docs.llamaindex.ai/en/stable/module_guides/deploying/query_engine/streaming/)
- [LlamaIndex OpenAILike](https://docs.llamaindex.ai/en/stable/api_reference/llms/openai_like/)
- [FastAPI WebSocket](https://fastapi.tiangolo.com/advanced/websockets/)

14
.flow/tasks/fn-1.1.json
View File

@@ -1,14 +0,0 @@
{
"assignee": null,
"claim_note": "",
"claimed_at": null,
"created_at": "2026-01-12T22:41:17.420190Z",
"depends_on": [],
"epic": "fn-1",
"id": "fn-1.1",
"priority": null,
"spec_path": ".flow/tasks/fn-1.1.md",
"status": "blocked",
"title": "WebSocket endpoint skeleton",
"updated_at": "2026-01-12T23:06:13.516408Z"
}

32
.flow/tasks/fn-1.1.md
View File

@@ -1,32 +0,0 @@
# fn-1.1 WebSocket endpoint skeleton
## Description
TBD
## Acceptance
- [ ] TBD
## Done summary
Blocked:
Auto-blocked after 5 attempts.
Run: 20260112T225250Z-duffy-igor.loskutoff@gmail.com-45256-e619
Task: fn-1.1
Last output:
timeout: failed to run command ‘claude’: No such file or directory
ralph: missing impl review receipt; forcing retry
ralph: task not done; forcing retry
Blocked:
Auto-blocked after 5 attempts.
Run: 20260112T230602Z-duffy-igor.loskutoff@gmail.com-47912-91d9
Task: fn-1.1
Last output:
timeout: failed to run command ‘claude’: No such file or directory
ralph: missing impl review receipt; forcing retry
ralph: task not done; forcing retry
## Evidence
- Commits:
- Tests:
- PRs:

23
.flow/tasks/fn-1.2.json
View File

@@ -1,23 +0,0 @@
{
"assignee": "igor.loskutoff@gmail.com",
"claim_note": "",
"claimed_at": "2026-01-12T23:11:46.263763Z",
"created_at": "2026-01-12T22:41:17.501928Z",
"depends_on": [],
"epic": "fn-1",
"evidence": {
"commits": [
"dbb619e7fcf50634c6bc7b7a355183de2243131b"
],
"prs": [],
"tests": [
"pytest tests/test_transcript_formats.py::test_topics_to_webvtt_named"
]
},
"id": "fn-1.2",
"priority": null,
"spec_path": ".flow/tasks/fn-1.2.md",
"status": "done",
"title": "WebVTT context generation",
"updated_at": "2026-01-12T23:21:46.532277Z"
}

33
.flow/tasks/fn-1.2.md
View File

@@ -1,33 +0,0 @@
# fn-1.2 WebVTT context generation
## Description
TBD
## Acceptance
- [ ] TBD
## Done summary
- Implemented WebVTT context generation in transcript chat WebSocket endpoint
- Added `_get_is_multitrack()` helper to detect multitrack recordings
- WebVTT generated on connection using existing `topics_to_webvtt_named()` utility
- Added `get_context` message type to retrieve WebVTT context
- Maintained backward compatibility with echo functionality
- Created test fixture `test_transcript_with_content` with participants and words
- Added test for WebVTT context generation via get_context message
**Why:**
- Provides transcript context for LLM integration in next task (fn-1.3)
- Reuses existing, well-tested WebVTT generation utility
- Supports both multitrack and standard recordings
**Verification:**
- Core WebVTT generation tested: `pytest tests/test_transcript_formats.py::test_topics_to_webvtt_named` passes
- Linting clean: no ruff errors on changed files
- WebSocket tests have pre-existing infrastructure issue (async pool) affecting all tests, not related to changes
**Note:**
WebSocket tests fail due to pre-existing test infrastructure issue with asyncpg pool cleanup. This affects all WebSocket tests, not just the new test. Core functionality verified via unit test of `topics_to_webvtt_named()`.
## Evidence
- Commits: dbb619e7fcf50634c6bc7b7a355183de2243131b
- Tests: pytest tests/test_transcript_formats.py::test_topics_to_webvtt_named
- PRs:

21
.flow/tasks/fn-1.3.json
View File

@@ -1,21 +0,0 @@
{
"assignee": "igor.loskutoff@gmail.com",
"claim_note": "",
"claimed_at": "2026-01-12T23:32:25.678580Z",
"created_at": "2026-01-12T22:41:17.581755Z",
"depends_on": [],
"epic": "fn-1",
"evidence": {
"commits": [
"ae85f5d3"
],
"prs": [],
"tests": []
},
"id": "fn-1.3",
"priority": null,
"spec_path": ".flow/tasks/fn-1.3.md",
"status": "done",
"title": "LLM streaming integration",
"updated_at": "2026-01-12T23:38:21.844470Z"
}

26
.flow/tasks/fn-1.3.md
View File

@@ -1,26 +0,0 @@
# fn-1.3 LLM streaming integration
## Description
TBD
## Acceptance
- [ ] TBD
## Done summary
- Added LLM streaming integration to transcript chat WebSocket endpoint
- Configured LLM with temperature 0.7 using llama-index Settings
- Built system message with WebVTT transcript context (15k char limit)
- Implemented conversation history management with ChatMessage objects
- Stream LLM responses using Settings.llm.astream_chat()
- Send tokens incrementally via WebSocket 'token' messages
- Added 'done' message after streaming completes
- Error handling with 'error' message type
Verification:
- Code matches task spec requirements
- WebSocket message protocol implemented (message/token/done/error)
- Route registered in app.py
## Evidence
- Commits: ae85f5d3
- Tests:
- PRs:

21
.flow/tasks/fn-1.4.json
View File

@@ -1,21 +0,0 @@
{
"assignee": "igor.loskutoff@gmail.com",
"claim_note": "",
"claimed_at": "2026-01-13T00:38:35.229751Z",
"created_at": "2026-01-12T22:41:17.670877Z",
"depends_on": [],
"epic": "fn-1",
"evidence": {
"commits": [
"b461ebb488cdff46c585207adb894baf50ac36b0"
],
"prs": [],
"tests": []
},
"id": "fn-1.4",
"priority": null,
"spec_path": ".flow/tasks/fn-1.4.md",
"status": "done",
"title": "Register WebSocket route",
"updated_at": "2026-01-13T00:39:01.958372Z"
}

19
.flow/tasks/fn-1.4.md
View File

@@ -1,19 +0,0 @@
# fn-1.4 Register WebSocket route
## Description
TBD
## Acceptance
- [ ] TBD
## Done summary
- Registered transcripts_chat_router in FastAPI app (server/reflector/app.py:94)
- WebSocket route `/v1/transcripts/{id}/chat` now available
- Imports transcripts_chat router module (line 21)
- Routes registered with /v1 prefix for API versioning
This completes the backend WebSocket route registration. The endpoint is now accessible at `ws://localhost:1250/v1/transcripts/{transcript_id}/chat` and integrates with existing auth infrastructure.
## Evidence
- Commits: b461ebb488cdff46c585207adb894baf50ac36b0
- Tests:
- PRs:

26
.flow/tasks/fn-1.5.json
View File

@@ -1,26 +0,0 @@
{
"assignee": "igor.loskutoff@gmail.com",
"claim_note": "",
"claimed_at": "2026-01-13T00:45:16.020313Z",
"created_at": "2026-01-12T22:41:17.754066Z",
"depends_on": [],
"epic": "fn-1",
"evidence": {
"commit": "2dfe82afbc26ab469915d02b61dcf0c66b0335d7",
"files": [
"www/app/(app)/transcripts/useTranscriptChat.ts"
],
"verification": [
"TypeScript compilation successful (no errors for useTranscriptChat)",
"Proper WebSocket lifecycle management with cleanup",
"Memory leak prevention with isMountedRef",
"Type-safe Message and UseTranscriptChat interfaces"
]
},
"id": "fn-1.5",
"priority": null,
"spec_path": ".flow/tasks/fn-1.5.md",
"status": "done",
"title": "Frontend WebSocket hook",
"updated_at": "2026-01-13T00:46:35.699645Z"
}

37
.flow/tasks/fn-1.5.md
View File

@@ -1,37 +0,0 @@
# fn-1.5 Frontend WebSocket hook
## Description
Implement React hook `useTranscriptChat` for bidirectional WebSocket chat with transcript assistant.
## Acceptance
- [x] Hook exported from `www/app/(app)/transcripts/useTranscriptChat.ts`
- [x] Connects to `/v1/transcripts/{transcriptId}/chat` WebSocket endpoint
- [x] Manages messages array with user and assistant messages
- [x] Handles streaming tokens (`type: "token"`) with proper accumulation
- [x] Handles completion (`type: "done"`) by adding message to history
- [x] Handles errors (`type: "error"`) with console logging
- [x] Provides `sendMessage(text)` function for user input
- [x] Returns `{messages, sendMessage, isStreaming, currentStreamingText}`
- [x] Proper TypeScript types (Message, UseTranscriptChat)
- [x] Memory leak prevention (isMounted check, proper cleanup)
- [x] WebSocket cleanup on unmount
## Done summary
Implemented useTranscriptChat React hook with WebSocket streaming, message management, and TypeScript types.
The hook provides:
- Bidirectional WebSocket connection to `/v1/transcripts/{transcriptId}/chat`
- Token streaming with ref-based accumulation (prevents stale closures)
- Conversation history management (user + assistant messages)
- Proper mounted state tracking to prevent memory leaks
- TypeScript type safety with Message and UseTranscriptChat interfaces
- WebSocket lifecycle management (connect, cleanup on unmount)
Production-ready improvements over spec:
- `streamingTextRef` instead of state-based accumulation (avoids closure bugs)
- `isMountedRef` for preventing setState on unmounted component
- Proper TypeScript typing for all exports
## Evidence
- Commits:
- Tests:
- PRs:

23
.flow/tasks/fn-1.6.json
View File

@@ -1,23 +0,0 @@
{
"assignee": "igor.loskutoff@gmail.com",
"claim_note": "",
"claimed_at": "2026-01-13T00:52:01.366013Z",
"created_at": "2026-01-12T22:41:17.835044Z",
"depends_on": [],
"epic": "fn-1",
"evidence": {
"commits": [
"d5a77087594b3b54150e78466132f2dfa001901b"
],
"prs": [],
"tests": [
"pnpm tsc --noEmit"
]
},
"id": "fn-1.6",
"priority": null,
"spec_path": ".flow/tasks/fn-1.6.md",
"status": "done",
"title": "Chat dialog component",
"updated_at": "2026-01-13T00:58:52.502248Z"
}

17
.flow/tasks/fn-1.6.md
View File

@@ -1,17 +0,0 @@
# fn-1.6 Chat dialog component
## Description
TBD
## Acceptance
- [ ] TBD
## Done summary
- Created TranscriptChatModal component with Dialog UI
- Added TranscriptChatButton floating action button
- Implemented message display with streaming indicator
- Added input field with Enter key support
## Evidence
- Commits: d5a77087594b3b54150e78466132f2dfa001901b
- Tests: pnpm tsc --noEmit
- PRs:

23
.flow/tasks/fn-1.7.json
View File

@@ -1,23 +0,0 @@
{
"assignee": "igor.loskutoff@gmail.com",
"claim_note": "",
"claimed_at": "2026-01-13T01:00:42.868632Z",
"created_at": "2026-01-12T22:41:17.915169Z",
"depends_on": [],
"epic": "fn-1",
"evidence": {
"commits": [
"e7dc003a1dacdbc1992265e6c5b0f0cf522f8530"
],
"prs": [],
"tests": [
"pnpm format"
]
},
"id": "fn-1.7",
"priority": null,
"spec_path": ".flow/tasks/fn-1.7.md",
"status": "done",
"title": "Integrate into transcript page",
"updated_at": "2026-01-13T01:08:49.593046Z"
}

32
.flow/tasks/fn-1.7.md
View File

@@ -1,32 +0,0 @@
# fn-1.7 Integrate into transcript page
## Description
Add TranscriptChatModal and TranscriptChatButton to the transcript details page. Use `useDisclosure` hook for modal state, instantiate `useTranscriptChat` hook with transcriptId, and render both components.
## Acceptance
- [ ] Import useDisclosure from @chakra-ui/react
- [ ] Import TranscriptChatModal and TranscriptChatButton components
- [ ] Import useTranscriptChat hook
- [ ] Add useDisclosure hook for modal open/close state
- [ ] Add useTranscriptChat hook with transcriptId
- [ ] Render TranscriptChatModal with all required props
- [ ] Render TranscriptChatButton with onClick handler
- [ ] Floating button appears on transcript page
- [ ] Click button opens chat dialog
- [ ] Dialog integrates with existing page layout
## Done summary
- Added TranscriptChatModal and TranscriptChatButton to transcript details page
- Imported useDisclosure hook from @chakra-ui/react for modal state management
- Integrated useTranscriptChat hook with transcriptId for WebSocket connection
- Rendered floating chat button in bottom-right corner and modal dialog
- Chat interface now accessible from all completed transcript pages
Verification:
- Code formatting passed (pnpm format)
- Pre-commit hooks passed
- Integration follows existing patterns from PRD spec
## Evidence
- Commits: e7dc003a1dacdbc1992265e6c5b0f0cf522f8530
- Tests: pnpm format
- PRs:

32
.flow/tasks/fn-1.8.json
View File

@@ -1,32 +0,0 @@
{
"assignee": "igor.loskutoff@gmail.com",
"claim_note": "",
"claimed_at": "2026-01-13T01:10:06.678780Z",
"created_at": "2026-01-12T22:41:17.996329Z",
"depends_on": [],
"epic": "fn-1",
"evidence": {
"commits": [
"68df8257"
],
"files_changed": [
".flow/tasks/fn-1.8.json",
".flow/tasks/fn-1.8.md",
"server/tests/test_transcripts_chat.py"
],
"tests": [
"test_chat_websocket_connection_success",
"test_chat_websocket_nonexistent_transcript",
"test_chat_websocket_multiple_messages",
"test_chat_websocket_disconnect_graceful",
"test_chat_websocket_context_generation",
"test_chat_websocket_unknown_message_type"
]
},
"id": "fn-1.8",
"priority": null,
"spec_path": ".flow/tasks/fn-1.8.md",
"status": "done",
"title": "End-to-end testing",
"updated_at": "2026-01-13T01:18:10.893171Z"
}

43
.flow/tasks/fn-1.8.md
View File

@@ -1,43 +0,0 @@
# fn-1.8 End-to-end testing
## Description
Fix WebSocket chat tests to use proper async WebSocket testing approach (matching existing `test_transcripts_rtc_ws.py` pattern) instead of TestClient which has event loop issues.
## Current State
- Backend endpoint implemented: `server/reflector/views/transcripts_chat.py`
- Frontend components implemented: `useTranscriptChat.ts`, `TranscriptChatModal.tsx`
- Integration complete: chat components added to transcript page
- Basic tests exist but fail due to TestClient event loop issues
## Acceptance
- [x] All WebSocket chat tests pass using proper async approach (httpx_ws)
- [x] Tests validate: connection, message protocol, context generation, error handling
- [x] Tests use threaded server pattern matching `test_transcripts_rtc_ws.py`
- [x] No event loop or asyncio errors in test output
## Done summary
Fixed WebSocket chat tests by switching from TestClient to proper async testing with httpx_ws and threaded server pattern. All 6 tests now pass without event loop errors.
## Changes
- Rewrote all WebSocket tests to use aconnect_ws from httpx_ws
- Added chat_appserver fixture using threaded Uvicorn server (port 1256)
- Tests now use separate event loop in server thread
- Matches existing pattern from test_transcripts_rtc_ws.py
## Tests Passing
All 6 tests now pass:
1. test_chat_websocket_connection_success - validates WebSocket connection and echo behavior
2. test_chat_websocket_nonexistent_transcript - validates error handling for invalid transcript
3. test_chat_websocket_multiple_messages - validates handling multiple sequential messages
4. test_chat_websocket_disconnect_graceful - validates clean disconnection
5. test_chat_websocket_context_generation - validates WebVTT context generation
6. test_chat_websocket_unknown_message_type - validates echo for unknown message types
## Evidence
- Commits: 68df8257
- Tests: test_chat_websocket_connection_success, test_chat_websocket_nonexistent_transcript, test_chat_websocket_multiple_messages, test_chat_websocket_disconnect_graceful, test_chat_websocket_context_generation, test_chat_websocket_unknown_message_type
- PRs:

76
.flow/usage.md
View File

@@ -1,76 +0,0 @@
# Flow-Next Usage Guide
Task tracking for AI agents. All state lives in `.flow/`.
## CLI
```bash
.flow/bin/flowctl --help # All commands
.flow/bin/flowctl <cmd> --help # Command help
```
## File Structure
```
.flow/
├── bin/flowctl # CLI (this install)
├── epics/fn-N.json # Epic metadata
├── specs/fn-N.md # Epic specifications
├── tasks/fn-N.M.json # Task metadata
├── tasks/fn-N.M.md # Task specifications
├── memory/ # Context memory
└── meta.json # Project metadata
```
## IDs
- Epics: `fn-N` (e.g., fn-1, fn-2)
- Tasks: `fn-N.M` (e.g., fn-1.1, fn-1.2)
## Common Commands
```bash
# List
.flow/bin/flowctl list # All epics + tasks grouped
.flow/bin/flowctl epics # All epics with progress
.flow/bin/flowctl tasks # All tasks
.flow/bin/flowctl tasks --epic fn-1 # Tasks for epic
.flow/bin/flowctl tasks --status todo # Filter by status
# View
.flow/bin/flowctl show fn-1 # Epic with all tasks
.flow/bin/flowctl show fn-1.2 # Single task
.flow/bin/flowctl cat fn-1 # Epic spec (markdown)
.flow/bin/flowctl cat fn-1.2 # Task spec (markdown)
# Status
.flow/bin/flowctl ready --epic fn-1 # What's ready to work on
.flow/bin/flowctl validate --all # Check structure
# Create
.flow/bin/flowctl epic create --title "..."
.flow/bin/flowctl task create --epic fn-1 --title "..."
# Work
.flow/bin/flowctl start fn-1.2 # Claim task
.flow/bin/flowctl done fn-1.2 --summary-file s.md --evidence-json e.json
```
## Workflow
1. `.flow/bin/flowctl epics` - list all epics
2. `.flow/bin/flowctl ready --epic fn-N` - find available tasks
3. `.flow/bin/flowctl start fn-N.M` - claim task
4. Implement the task
5. `.flow/bin/flowctl done fn-N.M --summary-file ... --evidence-json ...` - complete
## Evidence JSON Format
```json
{"commits": ["abc123"], "tests": ["npm test"], "prs": []}
```
## More Info
- Human docs: https://github.com/gmickel/gmickel-claude-marketplace/blob/main/plugins/flow-next/docs/flowctl.md
- CLI reference: `.flow/bin/flowctl --help`

2
scripts/ralph/.gitignore vendored
View File

@@ -1,2 +0,0 @@
runs/
*.log

4
scripts/ralph/flowctl
View File

@@ -1,4 +0,0 @@
#!/bin/bash
# flowctl wrapper - invokes flowctl.py from the same directory
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
exec python3 "$SCRIPT_DIR/flowctl.py" "$@"

3960
scripts/ralph/flowctl.py
View File

File diff suppressed because it is too large Load Diff

58
scripts/ralph/prompt_plan.md
View File

@@ -1,58 +0,0 @@
You are running one Ralph plan gate iteration.
Inputs:
- EPIC_ID={{EPIC_ID}}
- PLAN_REVIEW={{PLAN_REVIEW}}
- REQUIRE_PLAN_REVIEW={{REQUIRE_PLAN_REVIEW}}
Steps:
1) Re-anchor:
- scripts/ralph/flowctl show {{EPIC_ID}} --json
- scripts/ralph/flowctl cat {{EPIC_ID}}
- git status
- git log -10 --oneline
Ralph mode rules (must follow):
- If PLAN_REVIEW=rp: use `flowctl rp` wrappers (setup-review, select-add, prompt-get, chat-send).
- If PLAN_REVIEW=codex: use `flowctl codex` wrappers (plan-review with --receipt).
- Write receipt via bash heredoc (no Write tool) if `REVIEW_RECEIPT_PATH` set.
- If any rule is violated, output `<promise>RETRY</promise>` and stop.
2) Plan review gate:
- If PLAN_REVIEW=rp: run `/flow-next:plan-review {{EPIC_ID}} --review=rp`
- If PLAN_REVIEW=codex: run `/flow-next:plan-review {{EPIC_ID}} --review=codex`
- If PLAN_REVIEW=export: run `/flow-next:plan-review {{EPIC_ID}} --review=export`
- If PLAN_REVIEW=none:
- If REQUIRE_PLAN_REVIEW=1: output `<promise>RETRY</promise>` and stop.
- Else: set ship and stop:
`scripts/ralph/flowctl epic set-plan-review-status {{EPIC_ID}} --status ship --json`
3) The skill will loop internally until `<verdict>SHIP</verdict>`:
- First review uses `--new-chat`
- If NEEDS_WORK: skill fixes plan, re-reviews in SAME chat (no --new-chat)
- Repeats until SHIP
- Only returns to Ralph after SHIP or MAJOR_RETHINK
4) IMMEDIATELY after SHIP verdict, write receipt (for rp mode):
```bash
mkdir -p "$(dirname '{{REVIEW_RECEIPT_PATH}}')"
ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
cat > '{{REVIEW_RECEIPT_PATH}}' <<EOF
{"type":"plan_review","id":"{{EPIC_ID}}","mode":"rp","timestamp":"$ts"}
EOF
```
For codex mode, receipt is written automatically by `flowctl codex plan-review --receipt`.
**CRITICAL: Copy EXACTLY. The `"id":"{{EPIC_ID}}"` field is REQUIRED.**
Missing id = verification fails = forced retry.
5) After SHIP:
- `scripts/ralph/flowctl epic set-plan-review-status {{EPIC_ID}} --status ship --json`
- stop (do NOT output promise tag)
6) If MAJOR_RETHINK (rare):
- `scripts/ralph/flowctl epic set-plan-review-status {{EPIC_ID}} --status needs_work --json`
- output `<promise>FAIL</promise>` and stop
7) On hard failure, output `<promise>FAIL</promise>` and stop.
Do NOT output `<promise>COMPLETE</promise>` in this prompt.

51
scripts/ralph/prompt_work.md
View File

@@ -1,51 +0,0 @@
You are running one Ralph work iteration.
Inputs:
- TASK_ID={{TASK_ID}}
- BRANCH_MODE={{BRANCH_MODE_EFFECTIVE}}
- WORK_REVIEW={{WORK_REVIEW}}
## Steps (execute ALL in order)
**Step 1: Execute task**
```
/flow-next:work {{TASK_ID}} --branch={{BRANCH_MODE_EFFECTIVE}} --review={{WORK_REVIEW}}
```
When `--review=rp`, the work skill MUST invoke `/flow-next:impl-review` internally (see Phase 7 in skill).
When `--review=codex`, the work skill uses `flowctl codex impl-review` for review.
The impl-review skill handles review coordination and requires `<verdict>SHIP|NEEDS_WORK|MAJOR_RETHINK</verdict>` from reviewer.
Do NOT improvise review prompts - the skill has the correct format.
**Step 2: Verify task done** (AFTER skill returns)
```bash
scripts/ralph/flowctl show {{TASK_ID}} --json
```
If status != `done`, output `<promise>RETRY</promise>` and stop.
**Step 3: Write impl receipt** (MANDATORY if WORK_REVIEW=rp or codex)
For rp mode:
```bash
mkdir -p "$(dirname '{{REVIEW_RECEIPT_PATH}}')"
ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
cat > '{{REVIEW_RECEIPT_PATH}}' <<EOF
{"type":"impl_review","id":"{{TASK_ID}}","mode":"rp","timestamp":"$ts"}
EOF
echo "Receipt written: {{REVIEW_RECEIPT_PATH}}"
```
For codex mode, receipt is written automatically by `flowctl codex impl-review --receipt`.
**CRITICAL: Copy the command EXACTLY. The `"id":"{{TASK_ID}}"` field is REQUIRED.**
Ralph verifies receipts match this exact schema. Missing id = verification fails = forced retry.
**Step 4: Validate epic**
```bash
scripts/ralph/flowctl validate --epic $(echo {{TASK_ID}} | sed 's/\.[0-9]*$//') --json
```
**Step 5: On hard failure** → output `<promise>FAIL</promise>` and stop.
## Rules
- Must run `flowctl done` and verify task status is `done` before commit.
- Must `git add -A` (never list files).
- Do NOT use TodoWrite.
Do NOT output `<promise>COMPLETE</promise>` in this prompt.

907
scripts/ralph/ralph.sh
View File

@@ -1,907 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
CONFIG="$SCRIPT_DIR/config.env"
FLOWCTL="$SCRIPT_DIR/flowctl"
fail() { echo "ralph: $*" >&2; exit 1; }
log() {
# Machine-readable logs: only show when UI disabled
[[ "${UI_ENABLED:-1}" != "1" ]] && echo "ralph: $*"
return 0
}
# ─────────────────────────────────────────────────────────────────────────────
# Presentation layer (human-readable output)
# ─────────────────────────────────────────────────────────────────────────────
UI_ENABLED="${RALPH_UI:-1}" # set RALPH_UI=0 to disable
# Timing
START_TIME="$(date +%s)"
elapsed_time() {
local now elapsed mins secs
now="$(date +%s)"
elapsed=$((now - START_TIME))
mins=$((elapsed / 60))
secs=$((elapsed % 60))
printf "%d:%02d" "$mins" "$secs"
}
# Stats tracking
STATS_TASKS_DONE=0
# Colors (disabled if not tty or NO_COLOR set)
if [[ -t 1 && -z "${NO_COLOR:-}" ]]; then
C_RESET='\033[0m'
C_BOLD='\033[1m'
C_DIM='\033[2m'
C_BLUE='\033[34m'
C_GREEN='\033[32m'
C_YELLOW='\033[33m'
C_RED='\033[31m'
C_CYAN='\033[36m'
C_MAGENTA='\033[35m'
else
C_RESET='' C_BOLD='' C_DIM='' C_BLUE='' C_GREEN='' C_YELLOW='' C_RED='' C_CYAN='' C_MAGENTA=''
fi
# Watch mode: "", "tools", "verbose"
WATCH_MODE=""
ui() {
[[ "$UI_ENABLED" == "1" ]] || return 0
echo -e "$*"
}
# Get title from epic/task JSON
get_title() {
local json="$1"
python3 - "$json" <<'PY'
import json, sys
try:
data = json.loads(sys.argv[1])
print(data.get("title", "")[:40])
except:
print("")
PY
}
# Count progress (done/total tasks for scoped epics)
get_progress() {
python3 - "$ROOT_DIR" "${EPICS_FILE:-}" <<'PY'
import json, sys
from pathlib import Path
root = Path(sys.argv[1])
epics_file = sys.argv[2] if len(sys.argv) > 2 else ""
flow_dir = root / ".flow"
# Get scoped epics or all
scoped = []
if epics_file:
try:
scoped = json.load(open(epics_file))["epics"]
except:
pass
epics_dir = flow_dir / "epics"
tasks_dir = flow_dir / "tasks"
if not epics_dir.exists():
print("0|0|0|0")
sys.exit(0)
epic_ids = []
for f in sorted(epics_dir.glob("fn-*.json")):
eid = f.stem
if not scoped or eid in scoped:
epic_ids.append(eid)
epics_done = sum(1 for e in epic_ids if json.load(open(epics_dir / f"{e}.json")).get("status") == "done")
tasks_total = 0
tasks_done = 0
if tasks_dir.exists():
for tf in tasks_dir.glob("*.json"):
try:
t = json.load(open(tf))
epic_id = tf.stem.rsplit(".", 1)[0]
if not scoped or epic_id in scoped:
tasks_total += 1
if t.get("status") == "done":
tasks_done += 1
except:
pass
print(f"{epics_done}|{len(epic_ids)}|{tasks_done}|{tasks_total}")
PY
}
# Get git diff stats
get_git_stats() {
local base_branch="${1:-main}"
local stats
stats="$(git -C "$ROOT_DIR" diff --shortstat "$base_branch"...HEAD 2>/dev/null || true)"
if [[ -z "$stats" ]]; then
echo ""
return
fi
python3 - "$stats" <<'PY'
import re, sys
s = sys.argv[1]
files = re.search(r"(\d+) files? changed", s)
ins = re.search(r"(\d+) insertions?", s)
dels = re.search(r"(\d+) deletions?", s)
f = files.group(1) if files else "0"
i = ins.group(1) if ins else "0"
d = dels.group(1) if dels else "0"
print(f"{f} files, +{i} -{d}")
PY
}
ui_header() {
ui ""
ui "${C_BOLD}${C_BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RESET}"
ui "${C_BOLD}${C_BLUE} 🤖 Ralph Autonomous Loop${C_RESET}"
ui "${C_BOLD}${C_BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RESET}"
}
ui_config() {
local git_branch progress_info epics_done epics_total tasks_done tasks_total
git_branch="$(git -C "$ROOT_DIR" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")"
progress_info="$(get_progress)"
IFS='|' read -r epics_done epics_total tasks_done tasks_total <<< "$progress_info"
ui ""
ui "${C_DIM} Branch:${C_RESET} ${C_BOLD}$git_branch${C_RESET}"
ui "${C_DIM} Progress:${C_RESET} Epic ${epics_done}/${epics_total} ${C_DIM}•${C_RESET} Task ${tasks_done}/${tasks_total}"
local plan_display="$PLAN_REVIEW" work_display="$WORK_REVIEW"
[[ "$PLAN_REVIEW" == "rp" ]] && plan_display="RepoPrompt"
[[ "$PLAN_REVIEW" == "codex" ]] && plan_display="Codex"
[[ "$WORK_REVIEW" == "rp" ]] && work_display="RepoPrompt"
[[ "$WORK_REVIEW" == "codex" ]] && work_display="Codex"
ui "${C_DIM} Reviews:${C_RESET} Plan=$plan_display ${C_DIM}•${C_RESET} Work=$work_display"
[[ -n "${EPICS:-}" ]] && ui "${C_DIM} Scope:${C_RESET} $EPICS"
ui ""
}
ui_iteration() {
local iter="$1" status="$2" epic="${3:-}" task="${4:-}" title="" item_json=""
local elapsed
elapsed="$(elapsed_time)"
ui ""
ui "${C_BOLD}${C_CYAN}🔄 Iteration $iter${C_RESET} ${C_DIM}[${elapsed}]${C_RESET}"
if [[ "$status" == "plan" ]]; then
item_json="$("$FLOWCTL" show "$epic" --json 2>/dev/null || true)"
title="$(get_title "$item_json")"
ui " ${C_DIM}Epic:${C_RESET} ${C_BOLD}$epic${C_RESET} ${C_DIM}\"$title\"${C_RESET}"
ui " ${C_DIM}Phase:${C_RESET} ${C_YELLOW}Planning${C_RESET}"
elif [[ "$status" == "work" ]]; then
item_json="$("$FLOWCTL" show "$task" --json 2>/dev/null || true)"
title="$(get_title "$item_json")"
ui " ${C_DIM}Task:${C_RESET} ${C_BOLD}$task${C_RESET} ${C_DIM}\"$title\"${C_RESET}"
ui " ${C_DIM}Phase:${C_RESET} ${C_MAGENTA}Implementation${C_RESET}"
fi
}
ui_plan_review() {
local mode="$1" epic="$2"
if [[ "$mode" == "rp" ]]; then
ui ""
ui " ${C_YELLOW}📝 Plan Review${C_RESET}"
ui " ${C_DIM}Sending to reviewer via RepoPrompt...${C_RESET}"
elif [[ "$mode" == "codex" ]]; then
ui ""
ui " ${C_YELLOW}📝 Plan Review${C_RESET}"
ui " ${C_DIM}Sending to reviewer via Codex...${C_RESET}"
fi
}
ui_impl_review() {
local mode="$1" task="$2"
if [[ "$mode" == "rp" ]]; then
ui ""
ui " ${C_MAGENTA}🔍 Implementation Review${C_RESET}"
ui " ${C_DIM}Sending to reviewer via RepoPrompt...${C_RESET}"
elif [[ "$mode" == "codex" ]]; then
ui ""
ui " ${C_MAGENTA}🔍 Implementation Review${C_RESET}"
ui " ${C_DIM}Sending to reviewer via Codex...${C_RESET}"
fi
}
ui_task_done() {
local task="$1" git_stats=""
STATS_TASKS_DONE=$((STATS_TASKS_DONE + 1))
init_branches_file 2>/dev/null || true
local base_branch
base_branch="$(get_base_branch 2>/dev/null || echo "main")"
git_stats="$(get_git_stats "$base_branch")"
if [[ -n "$git_stats" ]]; then
ui " ${C_GREEN}✓${C_RESET} ${C_BOLD}$task${C_RESET} ${C_DIM}($git_stats)${C_RESET}"
else
ui " ${C_GREEN}✓${C_RESET} ${C_BOLD}$task${C_RESET}"
fi
}
ui_retry() {
local task="$1" attempts="$2" max="$3"
ui " ${C_YELLOW}↻ Retry${C_RESET} ${C_DIM}(attempt $attempts/$max)${C_RESET}"
}
ui_blocked() {
local task="$1"
ui " ${C_RED}🚫 Task blocked:${C_RESET} $task ${C_DIM}(max attempts reached)${C_RESET}"
}
ui_complete() {
local elapsed progress_info epics_done epics_total tasks_done tasks_total
elapsed="$(elapsed_time)"
progress_info="$(get_progress)"
IFS='|' read -r epics_done epics_total tasks_done tasks_total <<< "$progress_info"
ui ""
ui "${C_BOLD}${C_GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RESET}"
ui "${C_BOLD}${C_GREEN} ✅ Ralph Complete${C_RESET} ${C_DIM}[${elapsed}]${C_RESET}"
ui ""
ui " ${C_DIM}Tasks:${C_RESET} ${tasks_done}/${tasks_total} ${C_DIM}•${C_RESET} ${C_DIM}Epics:${C_RESET} ${epics_done}/${epics_total}"
ui "${C_BOLD}${C_GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RESET}"
ui ""
}
ui_fail() {
local reason="${1:-}" elapsed
elapsed="$(elapsed_time)"
ui ""
ui "${C_BOLD}${C_RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RESET}"
ui "${C_BOLD}${C_RED} ❌ Ralph Failed${C_RESET} ${C_DIM}[${elapsed}]${C_RESET}"
[[ -n "$reason" ]] && ui " ${C_DIM}$reason${C_RESET}"
ui "${C_BOLD}${C_RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RESET}"
ui ""
}
ui_waiting() {
ui " ${C_DIM}⏳ Claude working...${C_RESET}"
}
[[ -f "$CONFIG" ]] || fail "missing config.env"
[[ -x "$FLOWCTL" ]] || fail "missing flowctl"
# shellcheck disable=SC1090
set -a
source "$CONFIG"
set +a
MAX_ITERATIONS="${MAX_ITERATIONS:-25}"
MAX_TURNS="${MAX_TURNS:-}" # empty = no limit; Claude stops via promise tags
MAX_ATTEMPTS_PER_TASK="${MAX_ATTEMPTS_PER_TASK:-5}"
WORKER_TIMEOUT="${WORKER_TIMEOUT:-1800}" # 30min default; prevents stuck workers
BRANCH_MODE="${BRANCH_MODE:-new}"
PLAN_REVIEW="${PLAN_REVIEW:-none}"
WORK_REVIEW="${WORK_REVIEW:-none}"
REQUIRE_PLAN_REVIEW="${REQUIRE_PLAN_REVIEW:-0}"
YOLO="${YOLO:-0}"
EPICS="${EPICS:-}"
# Parse command line arguments
while [[ $# -gt 0 ]]; do
case "$1" in
--watch)
if [[ "${2:-}" == "verbose" ]]; then
WATCH_MODE="verbose"
shift
else
WATCH_MODE="tools"
fi
shift
;;
--help|-h)
echo "Usage: ralph.sh [options]"
echo ""
echo "Options:"
echo " --watch Show tool calls in real-time"
echo " --watch verbose Show tool calls + model responses"
echo " --help, -h Show this help"
echo ""
echo "Environment variables:"
echo " EPICS Comma/space-separated epic IDs to work on"
echo " MAX_ITERATIONS Max loop iterations (default: 25)"
echo " YOLO Set to 1 to skip permissions (required for unattended)"
echo ""
echo "See config.env for more options."
exit 0
;;
*)
fail "Unknown option: $1 (use --help for usage)"
;;
esac
done
# Set up signal trap for watch mode (pipe chains need clean Ctrl+C handling)
if [[ -n "$WATCH_MODE" ]]; then
cleanup() { kill -- -$$ 2>/dev/null; exit 130; }
trap cleanup SIGINT SIGTERM
fi
CLAUDE_BIN="${CLAUDE_BIN:-claude}"
# Detect timeout command (GNU coreutils). On macOS: brew install coreutils
if command -v timeout >/dev/null 2>&1; then
TIMEOUT_CMD="timeout"
elif command -v gtimeout >/dev/null 2>&1; then
TIMEOUT_CMD="gtimeout"
else
TIMEOUT_CMD=""
echo "ralph: warning: timeout command not found; worker timeout disabled (brew install coreutils)" >&2
fi
sanitize_id() {
local v="$1"
v="${v// /_}"
v="${v//\//_}"
v="${v//\\/__}"
echo "$v"
}
get_actor() {
if [[ -n "${FLOW_ACTOR:-}" ]]; then echo "$FLOW_ACTOR"; return; fi
if actor="$(git -C "$ROOT_DIR" config user.email 2>/dev/null)"; then
[[ -n "$actor" ]] && { echo "$actor"; return; }
fi
if actor="$(git -C "$ROOT_DIR" config user.name 2>/dev/null)"; then
[[ -n "$actor" ]] && { echo "$actor"; return; }
fi
echo "${USER:-unknown}"
}
rand4() {
python3 - <<'PY'
import secrets
print(secrets.token_hex(2))
PY
}
render_template() {
local path="$1"
python3 - "$path" <<'PY'
import os, sys
path = sys.argv[1]
text = open(path, encoding="utf-8").read()
keys = ["EPIC_ID","TASK_ID","PLAN_REVIEW","WORK_REVIEW","BRANCH_MODE","BRANCH_MODE_EFFECTIVE","REQUIRE_PLAN_REVIEW","REVIEW_RECEIPT_PATH"]
for k in keys:
text = text.replace("{{%s}}" % k, os.environ.get(k, ""))
print(text)
PY
}
json_get() {
local key="$1"
local json="$2"
python3 - "$key" "$json" <<'PY'
import json, sys
key = sys.argv[1]
data = json.loads(sys.argv[2])
val = data.get(key)
if val is None:
print("")
elif isinstance(val, bool):
print("1" if val else "0")
else:
print(val)
PY
}
ensure_attempts_file() {
[[ -f "$1" ]] || echo "{}" > "$1"
}
bump_attempts() {
python3 - "$1" "$2" <<'PY'
import json, sys, os
path, task = sys.argv[1], sys.argv[2]
data = {}
if os.path.exists(path):
with open(path, encoding="utf-8") as f:
data = json.load(f)
count = int(data.get(task, 0)) + 1
data[task] = count
with open(path, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, sort_keys=True)
print(count)
PY
}
write_epics_file() {
python3 - "$1" <<'PY'
import json, sys
raw = sys.argv[1]
parts = [p.strip() for p in raw.replace(",", " ").split() if p.strip()]
print(json.dumps({"epics": parts}, indent=2, sort_keys=True))
PY
}
RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$(hostname -s 2>/dev/null || hostname)-$(sanitize_id "$(get_actor)")-$$-$(rand4)"
RUN_DIR="$SCRIPT_DIR/runs/$RUN_ID"
mkdir -p "$RUN_DIR"
ATTEMPTS_FILE="$RUN_DIR/attempts.json"
ensure_attempts_file "$ATTEMPTS_FILE"
BRANCHES_FILE="$RUN_DIR/branches.json"
RECEIPTS_DIR="$RUN_DIR/receipts"
mkdir -p "$RECEIPTS_DIR"
PROGRESS_FILE="$RUN_DIR/progress.txt"
{
echo "# Ralph Progress Log"
echo "Run: $RUN_ID"
echo "Started: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo "---"
} > "$PROGRESS_FILE"
extract_tag() {
local tag="$1"
python3 - "$tag" <<'PY'
import re, sys
tag = sys.argv[1]
text = sys.stdin.read()
matches = re.findall(rf"<{tag}>(.*?)</{tag}>", text, flags=re.S)
print(matches[-1] if matches else "")
PY
}
# Extract assistant text from stream-json log (for tag extraction in watch mode)
extract_text_from_stream_json() {
local log_file="$1"
python3 - "$log_file" <<'PY'
import json, sys
path = sys.argv[1]
out = []
try:
with open(path, encoding="utf-8") as f:
for line in f:
line = line.strip()
if not line:
continue
try:
ev = json.loads(line)
except json.JSONDecodeError:
continue
if ev.get("type") != "assistant":
continue
msg = ev.get("message") or {}
for blk in (msg.get("content") or []):
if blk.get("type") == "text":
out.append(blk.get("text", ""))
except Exception:
pass
print("\n".join(out))
PY
}
append_progress() {
local verdict="$1"
local promise="$2"
local plan_review_status="${3:-}"
local task_status="${4:-}"
local receipt_exists="0"
if [[ -n "${REVIEW_RECEIPT_PATH:-}" && -f "$REVIEW_RECEIPT_PATH" ]]; then
receipt_exists="1"
fi
{
echo "## $(date -u +%Y-%m-%dT%H:%M:%SZ) - iter $iter"
echo "status=$status epic=${epic_id:-} task=${task_id:-} reason=${reason:-}"
echo "claude_rc=$claude_rc"
echo "verdict=${verdict:-}"
echo "promise=${promise:-}"
echo "receipt=${REVIEW_RECEIPT_PATH:-} exists=$receipt_exists"
echo "plan_review_status=${plan_review_status:-}"
echo "task_status=${task_status:-}"
echo "iter_log=$iter_log"
echo "last_output:"
tail -n 10 "$iter_log" || true
echo "---"
} >> "$PROGRESS_FILE"
}
init_branches_file() {
if [[ -f "$BRANCHES_FILE" ]]; then return; fi
local base_branch
base_branch="$(git -C "$ROOT_DIR" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
python3 - "$BRANCHES_FILE" "$base_branch" <<'PY'
import json, sys
path, base = sys.argv[1], sys.argv[2]
data = {"base_branch": base, "run_branch": ""}
with open(path, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, sort_keys=True)
PY
}
get_base_branch() {
python3 - "$BRANCHES_FILE" <<'PY'
import json, sys
try:
with open(sys.argv[1], encoding="utf-8") as f:
data = json.load(f)
print(data.get("base_branch", ""))
except FileNotFoundError:
print("")
PY
}
get_run_branch() {
python3 - "$BRANCHES_FILE" <<'PY'
import json, sys
try:
with open(sys.argv[1], encoding="utf-8") as f:
data = json.load(f)
print(data.get("run_branch", ""))
except FileNotFoundError:
print("")
PY
}
set_run_branch() {
python3 - "$BRANCHES_FILE" "$1" <<'PY'
import json, sys
path, branch = sys.argv[1], sys.argv[2]
data = {"base_branch": "", "run_branch": ""}
try:
with open(path, encoding="utf-8") as f:
data = json.load(f)
except FileNotFoundError:
pass
data["run_branch"] = branch
with open(path, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, sort_keys=True)
PY
}
list_epics_from_file() {
python3 - "$EPICS_FILE" <<'PY'
import json, sys
path = sys.argv[1]
if not path:
sys.exit(0)
try:
data = json.load(open(path, encoding="utf-8"))
except FileNotFoundError:
sys.exit(0)
epics = data.get("epics", []) or []
print(" ".join(epics))
PY
}
epic_all_tasks_done() {
python3 - "$1" <<'PY'
import json, sys
try:
data = json.loads(sys.argv[1])
except json.JSONDecodeError:
print("0")
sys.exit(0)
tasks = data.get("tasks", []) or []
if not tasks:
print("0")
sys.exit(0)
for t in tasks:
if t.get("status") != "done":
print("0")
sys.exit(0)
print("1")
PY
}
maybe_close_epics() {
[[ -z "$EPICS_FILE" ]] && return 0
local epics json status all_done
epics="$(list_epics_from_file)"
[[ -z "$epics" ]] && return 0
for epic in $epics; do
json="$("$FLOWCTL" show "$epic" --json 2>/dev/null || true)"
[[ -z "$json" ]] && continue
status="$(json_get status "$json")"
[[ "$status" == "done" ]] && continue
all_done="$(epic_all_tasks_done "$json")"
if [[ "$all_done" == "1" ]]; then
"$FLOWCTL" epic close "$epic" --json >/dev/null 2>&1 || true
fi
done
}
verify_receipt() {
local path="$1"
local kind="$2"
local id="$3"
[[ -f "$path" ]] || return 1
python3 - "$path" "$kind" "$id" <<'PY'
import json, sys
path, kind, rid = sys.argv[1], sys.argv[2], sys.argv[3]
try:
data = json.load(open(path, encoding="utf-8"))
except Exception:
sys.exit(1)
if data.get("type") != kind:
sys.exit(1)
if data.get("id") != rid:
sys.exit(1)
sys.exit(0)
PY
}
# Create/switch to run branch (once at start, all epics work here)
ensure_run_branch() {
if [[ "$BRANCH_MODE" != "new" ]]; then
return
fi
init_branches_file
local branch
branch="$(get_run_branch)"
if [[ -n "$branch" ]]; then
# Already on run branch (resumed run)
git -C "$ROOT_DIR" checkout "$branch" >/dev/null 2>&1 || true
return
fi
# Create new run branch from current position
branch="ralph-${RUN_ID}"
set_run_branch "$branch"
git -C "$ROOT_DIR" checkout -b "$branch" >/dev/null 2>&1
}
EPICS_FILE=""
if [[ -n "${EPICS// }" ]]; then
EPICS_FILE="$RUN_DIR/run.json"
write_epics_file "$EPICS" > "$EPICS_FILE"
fi
ui_header
ui_config
# Create run branch once at start (all epics work on same branch)
ensure_run_branch
iter=1
while (( iter <= MAX_ITERATIONS )); do
iter_log="$RUN_DIR/iter-$(printf '%03d' "$iter").log"
selector_args=("$FLOWCTL" next --json)
[[ -n "$EPICS_FILE" ]] && selector_args+=(--epics-file "$EPICS_FILE")
[[ "$REQUIRE_PLAN_REVIEW" == "1" ]] && selector_args+=(--require-plan-review)
selector_json="$("${selector_args[@]}")"
status="$(json_get status "$selector_json")"
epic_id="$(json_get epic "$selector_json")"
task_id="$(json_get task "$selector_json")"
reason="$(json_get reason "$selector_json")"
log "iter $iter status=$status epic=${epic_id:-} task=${task_id:-} reason=${reason:-}"
ui_iteration "$iter" "$status" "${epic_id:-}" "${task_id:-}"
if [[ "$status" == "none" ]]; then
if [[ "$reason" == "blocked_by_epic_deps" ]]; then
log "blocked by epic deps"
fi
maybe_close_epics
ui_complete
echo "<promise>COMPLETE</promise>"
exit 0
fi
if [[ "$status" == "plan" ]]; then
export EPIC_ID="$epic_id"
export PLAN_REVIEW
export REQUIRE_PLAN_REVIEW
if [[ "$PLAN_REVIEW" != "none" ]]; then
export REVIEW_RECEIPT_PATH="$RECEIPTS_DIR/plan-${epic_id}.json"
else
unset REVIEW_RECEIPT_PATH
fi
log "plan epic=$epic_id review=$PLAN_REVIEW receipt=${REVIEW_RECEIPT_PATH:-} require=$REQUIRE_PLAN_REVIEW"
ui_plan_review "$PLAN_REVIEW" "$epic_id"
prompt="$(render_template "$SCRIPT_DIR/prompt_plan.md")"
elif [[ "$status" == "work" ]]; then
epic_id="${task_id%%.*}"
export TASK_ID="$task_id"
BRANCH_MODE_EFFECTIVE="$BRANCH_MODE"
if [[ "$BRANCH_MODE" == "new" ]]; then
BRANCH_MODE_EFFECTIVE="current"
fi
export BRANCH_MODE_EFFECTIVE
export WORK_REVIEW
if [[ "$WORK_REVIEW" != "none" ]]; then
export REVIEW_RECEIPT_PATH="$RECEIPTS_DIR/impl-${task_id}.json"
else
unset REVIEW_RECEIPT_PATH
fi
log "work task=$task_id review=$WORK_REVIEW receipt=${REVIEW_RECEIPT_PATH:-} branch=$BRANCH_MODE_EFFECTIVE"
ui_impl_review "$WORK_REVIEW" "$task_id"
prompt="$(render_template "$SCRIPT_DIR/prompt_work.md")"
else
fail "invalid selector status: $status"
fi
export FLOW_RALPH="1"
claude_args=(-p)
# Set output format based on watch mode (stream-json required for real-time output)
if [[ -n "$WATCH_MODE" ]]; then
claude_args+=(--output-format stream-json)
else
claude_args+=(--output-format text)
fi
# Autonomous mode system prompt - critical for preventing drift
claude_args+=(--append-system-prompt "AUTONOMOUS MODE ACTIVE (FLOW_RALPH=1). You are running unattended. CRITICAL RULES:
1. EXECUTE COMMANDS EXACTLY as shown in prompts. Do not paraphrase or improvise.
2. VERIFY OUTCOMES by running the verification commands (flowctl show, git status).
3. NEVER CLAIM SUCCESS without proof. If flowctl done was not run, the task is NOT done.
4. COPY TEMPLATES VERBATIM - receipt JSON must match exactly including all fields.
5. USE SKILLS AS SPECIFIED - invoke /flow-next:impl-review, do not improvise review prompts.
Violations break automation and leave the user with incomplete work. Be precise, not creative.")
[[ -n "${MAX_TURNS:-}" ]] && claude_args+=(--max-turns "$MAX_TURNS")
[[ "$YOLO" == "1" ]] && claude_args+=(--dangerously-skip-permissions)
[[ -n "${FLOW_RALPH_CLAUDE_PLUGIN_DIR:-}" ]] && claude_args+=(--plugin-dir "$FLOW_RALPH_CLAUDE_PLUGIN_DIR")
[[ -n "${FLOW_RALPH_CLAUDE_MODEL:-}" ]] && claude_args+=(--model "$FLOW_RALPH_CLAUDE_MODEL")
[[ -n "${FLOW_RALPH_CLAUDE_SESSION_ID:-}" ]] && claude_args+=(--session-id "$FLOW_RALPH_CLAUDE_SESSION_ID")
[[ -n "${FLOW_RALPH_CLAUDE_PERMISSION_MODE:-}" ]] && claude_args+=(--permission-mode "$FLOW_RALPH_CLAUDE_PERMISSION_MODE")
[[ "${FLOW_RALPH_CLAUDE_NO_SESSION_PERSISTENCE:-}" == "1" ]] && claude_args+=(--no-session-persistence)
if [[ -n "${FLOW_RALPH_CLAUDE_DEBUG:-}" ]]; then
if [[ "${FLOW_RALPH_CLAUDE_DEBUG}" == "1" ]]; then
claude_args+=(--debug)
else
claude_args+=(--debug "$FLOW_RALPH_CLAUDE_DEBUG")
fi
fi
[[ "${FLOW_RALPH_CLAUDE_VERBOSE:-}" == "1" ]] && claude_args+=(--verbose)
ui_waiting
claude_out=""
set +e
[[ -n "${FLOW_RALPH_CLAUDE_PLUGIN_DIR:-}" ]] && claude_args+=(--plugin-dir "$FLOW_RALPH_CLAUDE_PLUGIN_DIR")
if [[ "$WATCH_MODE" == "verbose" ]]; then
# Full output: stream through filter with --verbose to show text/thinking
[[ ! " ${claude_args[*]} " =~ " --verbose " ]] && claude_args+=(--verbose)
echo ""
if [[ -n "$TIMEOUT_CMD" ]]; then
"$TIMEOUT_CMD" "$WORKER_TIMEOUT" "$CLAUDE_BIN" "${claude_args[@]}" "$prompt" 2>&1 | tee "$iter_log" | "$SCRIPT_DIR/watch-filter.py" --verbose
else
"$CLAUDE_BIN" "${claude_args[@]}" "$prompt" 2>&1 | tee "$iter_log" | "$SCRIPT_DIR/watch-filter.py" --verbose
fi
claude_rc=${PIPESTATUS[0]}
claude_out="$(cat "$iter_log")"
elif [[ "$WATCH_MODE" == "tools" ]]; then
# Filtered output: stream-json through watch-filter.py
# Add --verbose only if not already set (needed for tool visibility)
[[ ! " ${claude_args[*]} " =~ " --verbose " ]] && claude_args+=(--verbose)
if [[ -n "$TIMEOUT_CMD" ]]; then
"$TIMEOUT_CMD" "$WORKER_TIMEOUT" "$CLAUDE_BIN" "${claude_args[@]}" "$prompt" 2>&1 | tee "$iter_log" | "$SCRIPT_DIR/watch-filter.py"
else
"$CLAUDE_BIN" "${claude_args[@]}" "$prompt" 2>&1 | tee "$iter_log" | "$SCRIPT_DIR/watch-filter.py"
fi
claude_rc=${PIPESTATUS[0]}
# Log contains stream-json; verdict/promise extraction handled by fallback logic
claude_out="$(cat "$iter_log")"
else
# Default: quiet mode
if [[ -n "$TIMEOUT_CMD" ]]; then
claude_out="$("$TIMEOUT_CMD" "$WORKER_TIMEOUT" "$CLAUDE_BIN" "${claude_args[@]}" "$prompt" 2>&1)"
else
claude_out="$("$CLAUDE_BIN" "${claude_args[@]}" "$prompt" 2>&1)"
fi
claude_rc=$?
printf '%s\n' "$claude_out" > "$iter_log"
fi
set -e
# Handle timeout (exit code 124 from timeout command)
worker_timeout=0
if [[ -n "$TIMEOUT_CMD" && "$claude_rc" -eq 124 ]]; then
echo "ralph: worker timed out after ${WORKER_TIMEOUT}s" >> "$iter_log"
log "worker timeout after ${WORKER_TIMEOUT}s"
worker_timeout=1
fi
log "claude rc=$claude_rc log=$iter_log"
force_retry=$worker_timeout
plan_review_status=""
task_status=""
if [[ "$status" == "plan" && ( "$PLAN_REVIEW" == "rp" || "$PLAN_REVIEW" == "codex" ) ]]; then
if ! verify_receipt "$REVIEW_RECEIPT_PATH" "plan_review" "$epic_id"; then
echo "ralph: missing plan review receipt; forcing retry" >> "$iter_log"
log "missing plan receipt; forcing retry"
"$FLOWCTL" epic set-plan-review-status "$epic_id" --status needs_work --json >/dev/null 2>&1 || true
force_retry=1
fi
epic_json="$("$FLOWCTL" show "$epic_id" --json 2>/dev/null || true)"
plan_review_status="$(json_get plan_review_status "$epic_json")"
fi
if [[ "$status" == "work" && ( "$WORK_REVIEW" == "rp" || "$WORK_REVIEW" == "codex" ) ]]; then
if ! verify_receipt "$REVIEW_RECEIPT_PATH" "impl_review" "$task_id"; then
echo "ralph: missing impl review receipt; forcing retry" >> "$iter_log"
log "missing impl receipt; forcing retry"
force_retry=1
fi
fi
# Extract verdict/promise for progress log (not displayed in UI)
# In watch mode, parse stream-json to get assistant text; otherwise use raw output
if [[ -n "$WATCH_MODE" ]]; then
claude_text="$(extract_text_from_stream_json "$iter_log")"
else
claude_text="$claude_out"
fi
verdict="$(printf '%s' "$claude_text" | extract_tag verdict)"
promise="$(printf '%s' "$claude_text" | extract_tag promise)"
# Fallback: derive verdict from flowctl status for logging
if [[ -z "$verdict" && -n "$plan_review_status" ]]; then
case "$plan_review_status" in
ship) verdict="SHIP" ;;
needs_work) verdict="NEEDS_WORK" ;;
esac
fi
if [[ "$status" == "work" ]]; then
task_json="$("$FLOWCTL" show "$task_id" --json 2>/dev/null || true)"
task_status="$(json_get status "$task_json")"
if [[ "$task_status" != "done" ]]; then
echo "ralph: task not done; forcing retry" >> "$iter_log"
log "task $task_id status=$task_status; forcing retry"
force_retry=1
else
ui_task_done "$task_id"
# Derive verdict from task completion for logging
[[ -z "$verdict" ]] && verdict="SHIP"
fi
fi
append_progress "$verdict" "$promise" "$plan_review_status" "$task_status"
if echo "$claude_text" | grep -q "<promise>COMPLETE</promise>"; then
ui_complete
echo "<promise>COMPLETE</promise>"
exit 0
fi
exit_code=0
if echo "$claude_text" | grep -q "<promise>FAIL</promise>"; then
exit_code=1
elif echo "$claude_text" | grep -q "<promise>RETRY</promise>"; then
exit_code=2
elif [[ "$force_retry" == "1" ]]; then
exit_code=2
elif [[ "$claude_rc" -ne 0 && "$task_status" != "done" && "$verdict" != "SHIP" ]]; then
# Only fail on non-zero exit code if task didn't complete and verdict isn't SHIP
# This prevents false failures from transient errors (telemetry, model fallback, etc.)
exit_code=1
fi
if [[ "$exit_code" -eq 1 ]]; then
log "exit=fail"
ui_fail "Claude returned FAIL promise"
exit 1
fi
if [[ "$exit_code" -eq 2 && "$status" == "work" ]]; then
attempts="$(bump_attempts "$ATTEMPTS_FILE" "$task_id")"
log "retry task=$task_id attempts=$attempts"
ui_retry "$task_id" "$attempts" "$MAX_ATTEMPTS_PER_TASK"
if (( attempts >= MAX_ATTEMPTS_PER_TASK )); then
reason_file="$RUN_DIR/block-${task_id}.md"
{
echo "Auto-blocked after ${attempts} attempts."
echo "Run: $RUN_ID"
echo "Task: $task_id"
echo ""
echo "Last output:"
tail -n 40 "$iter_log" || true
} > "$reason_file"
"$FLOWCTL" block "$task_id" --reason-file "$reason_file" --json || true
ui_blocked "$task_id"
fi
fi
sleep 2
iter=$((iter + 1))
done
ui_fail "Max iterations ($MAX_ITERATIONS) reached"
echo "ralph: max iterations reached" >&2
exit 1

9
scripts/ralph/ralph_once.sh
View File

@@ -1,9 +0,0 @@
#!/usr/bin/env bash
# Human-in-the-loop Ralph: runs exactly one iteration
# Use this to observe behavior before going fully autonomous
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
export MAX_ITERATIONS=1
exec "$SCRIPT_DIR/ralph.sh" "$@"

230
scripts/ralph/watch-filter.py
View File

@@ -1,230 +0,0 @@
#!/usr/bin/env python3
"""
Watch filter for Ralph - parses Claude's stream-json output and shows key events.
Reads JSON lines from stdin, outputs formatted tool calls in TUI style.
CRITICAL: This filter is "fail open" - if output breaks, it continues draining
stdin to prevent SIGPIPE cascading to upstream processes (tee, claude).
Usage:
watch-filter.py # Show tool calls only
watch-filter.py --verbose # Show tool calls + thinking + text responses
"""
import argparse
import json
import os
import sys
from typing import Optional
# Global flag to disable output on pipe errors (fail open pattern)
_output_disabled = False
# ANSI color codes (match ralph.sh TUI)
if sys.stdout.isatty() and not os.environ.get("NO_COLOR"):
C_RESET = "\033[0m"
C_DIM = "\033[2m"
C_CYAN = "\033[36m"
else:
C_RESET = C_DIM = C_CYAN = ""
# TUI indentation (3 spaces to match ralph.sh)
INDENT = " "
# Tool icons
ICONS = {
"Bash": "🔧",
"Edit": "📝",
"Write": "📄",
"Read": "📖",
"Grep": "🔍",
"Glob": "📁",
"Task": "🤖",
"WebFetch": "🌐",
"WebSearch": "🔎",
"TodoWrite": "📋",
"AskUserQuestion": "❓",
"Skill": "⚡",
}
def safe_print(msg: str) -> None:
"""Print that fails open - disables output on BrokenPipe instead of crashing."""
global _output_disabled
if _output_disabled:
return
try:
print(msg, flush=True)
except BrokenPipeError:
_output_disabled = True
def drain_stdin() -> None:
"""Consume remaining stdin to prevent SIGPIPE to upstream processes."""
try:
for _ in sys.stdin:
pass
except Exception:
pass
def truncate(s: str, max_len: int = 60) -> str:
s = s.replace("\n", " ").strip()
if len(s) > max_len:
return s[: max_len - 3] + "..."
return s
def format_tool_use(tool_name: str, tool_input: dict) -> str:
"""Format a tool use event for TUI display."""
icon = ICONS.get(tool_name, "🔹")
if tool_name == "Bash":
cmd = tool_input.get("command", "")
desc = tool_input.get("description", "")
if desc:
return f"{icon} Bash: {truncate(desc)}"
return f"{icon} Bash: {truncate(cmd, 60)}"
elif tool_name == "Edit":
path = tool_input.get("file_path", "")
return f"{icon} Edit: {path.split('/')[-1] if path else 'unknown'}"
elif tool_name == "Write":
path = tool_input.get("file_path", "")
return f"{icon} Write: {path.split('/')[-1] if path else 'unknown'}"
elif tool_name == "Read":
path = tool_input.get("file_path", "")
return f"{icon} Read: {path.split('/')[-1] if path else 'unknown'}"
elif tool_name == "Grep":
pattern = tool_input.get("pattern", "")
return f"{icon} Grep: {truncate(pattern, 40)}"
elif tool_name == "Glob":
pattern = tool_input.get("pattern", "")
return f"{icon} Glob: {pattern}"
elif tool_name == "Task":
desc = tool_input.get("description", "")
agent = tool_input.get("subagent_type", "")
return f"{icon} Task ({agent}): {truncate(desc, 50)}"
elif tool_name == "Skill":
skill = tool_input.get("skill", "")
return f"{icon} Skill: {skill}"
elif tool_name == "TodoWrite":
todos = tool_input.get("todos", [])
in_progress = [t for t in todos if t.get("status") == "in_progress"]
if in_progress:
return f"{icon} Todo: {truncate(in_progress[0].get('content', ''))}"
return f"{icon} Todo: {len(todos)} items"
else:
return f"{icon} {tool_name}"
def format_tool_result(block: dict) -> Optional[str]:
"""Format a tool_result block (errors only).
Args:
block: The full tool_result block (not just content)
"""
# Check is_error on the block itself
if block.get("is_error"):
content = block.get("content", "")
error_text = str(content) if content else "unknown error"
return f"{INDENT}{C_DIM}❌ {truncate(error_text, 60)}{C_RESET}"
# Also check content for error strings (heuristic)
content = block.get("content", "")
if isinstance(content, str):
lower = content.lower()
if "error" in lower or "failed" in lower:
return f"{INDENT}{C_DIM}⚠️ {truncate(content, 60)}{C_RESET}"
return None
def process_event(event: dict, verbose: bool) -> None:
"""Process a single stream-json event."""
event_type = event.get("type", "")
# Tool use events (assistant messages)
if event_type == "assistant":
message = event.get("message", {})
content = message.get("content", [])
for block in content:
block_type = block.get("type", "")
if block_type == "tool_use":
tool_name = block.get("name", "")
tool_input = block.get("input", {})
formatted = format_tool_use(tool_name, tool_input)
safe_print(f"{INDENT}{C_DIM}{formatted}{C_RESET}")
elif verbose and block_type == "text":
text = block.get("text", "")
if text.strip():
safe_print(f"{INDENT}{C_CYAN}💬 {text}{C_RESET}")
elif verbose and block_type == "thinking":
thinking = block.get("thinking", "")
if thinking.strip():
safe_print(f"{INDENT}{C_DIM}🧠 {truncate(thinking, 100)}{C_RESET}")
# Tool results (user messages with tool_result blocks)
elif event_type == "user":
message = event.get("message", {})
content = message.get("content", [])
for block in content:
if block.get("type") == "tool_result":
formatted = format_tool_result(block)
if formatted:
safe_print(formatted)
def main() -> None:
parser = argparse.ArgumentParser(description="Filter Claude stream-json output")
parser.add_argument(
"--verbose",
action="store_true",
help="Show text and thinking in addition to tool calls",
)
args = parser.parse_args()
for line in sys.stdin:
line = line.strip()
if not line:
continue
try:
event = json.loads(line)
except json.JSONDecodeError:
continue
try:
process_event(event, args.verbose)
except Exception:
# Swallow processing errors - keep draining stdin
pass
if __name__ == "__main__":
try:
main()
except KeyboardInterrupt:
sys.exit(0)
except BrokenPipeError:
# Output broken but keep draining to prevent upstream SIGPIPE
drain_stdin()
sys.exit(0)
except Exception as e:
print(f"watch-filter: {e}", file=sys.stderr)
drain_stdin()
sys.exit(0)