M5: Python agent sidecar + SwiftUI agent panel

[kalil0321]

Stacked on top of #75. The actual reverse-engineering loop.

Backend (backend/)

New Python package rae-agent, totally independent of the existing CLI under src/reverse_api/ (no shared code, per spec).

• protocol.py — typed ChatRequest, FlowSummary, AgentEvent dataclasses with payload validation.
• prompts.py — system prompt + per-language guidelines (Python / TypeScript / Go).
• session.py — per-chat workdir under <base>/agent-sessions/<chat-id>/{flows,out}. Drives claude_agent_sdk.query with permission_mode="acceptEdits", allowed tools Read / Write / Edit. Translates AssistantMessage / UserMessage (tool results) / ResultMessage blocks into the AgentEvent stream.
• server.py — websockets server. Prints RAE_AGENT_LISTENING:<port> on bind so the Swift side can read the actual port.
• tests/test_protocol.py — 8 pytest cases on the protocol layer; all green.

macOS (macos/Sources/ReverseAPI/Agent/)

• AgentSidecar — actor that launches the Python backend, parses the bound port from stdout, manages lifecycle.
• AgentClient — actor wrapping URLSessionWebSocketTask with an AsyncThrowingStream<AgentEvent, Error>.
• AgentProtocol — AgentEvent, AgentFlowPayload, AgentChatRequest, AgentEventDecoder.
• AgentSession — @MainActor @Observable coordinator. Exposes status / events / history / generatedFiles / lastWorkdir, owns the sidecar + client, exposes send / clear / shutdown.

UI (macos/Sources/ReverseAPI/UI/AgentPanel.swift)

• Header with status dot + target picker + clear button
• Timeline: assistant text bubbles, tool-use cards, tool-result snippets, file-written badges, completion + error cards
• Generated files card with reveal-in-Finder
• Composer with multiline input + ⌘↩ shortcut

ContentView now lays out TrafficListView | InspectorView | AgentPanel in a 3-pane HSplitView.

Try it

# once:
cd backend && pip install -e .

# run app:
cd ../macos && swift run ReverseAPI

The agent uses whichever python3 is on PATH. App Support layout:

~/Library/Application Support/ReverseAPI/
  ├── root.cer
  ├── flows.sqlite
  └── agent-sessions/
      └── <chat-id>/{flows.json, out/*}

---

Generated by Claude Code

---

Summary by cubic

Adds a Python rae-agent sidecar and a SwiftUI Agent Panel that turn captured flows into a generated API client. The traffic card now uses a single Filter button popover and a smooth transparent split; rows also show request duration next to the timestamp.

• New Features

  • Backend (rae-agent): WebSocket server on claude-agent-sdk (Read/Write/Edit, bypassPermissions); per‑chat workdir; validated ChatRequest/FlowSummary; incremental text chunks and session_started; persists selected flows to JSON; prints bound port; resume via claude_session_id; base dir honors RAE_AGENT_WORKDIR. Tests cover protocol, base‑dir resolution, and session‑dir safety.
  • macOS: Sidecar launcher + resilient WebSocket client; Agent Panel with sessions list, timeline, flow selection, and generated files viewer sheet; assistant Markdown via swift-markdown-ui with syntax highlighting; compact tool/use result rows; improved inspector with Preview (images/HTML); command palette. Traffic card has a Filter button popover (chips for type/method/status, custom text filter, Reset inside; shows a dot when filters are active), a delete‑all button, and rows show request duration. Cards use a custom transparent split for smoother resizing; sessions auto‑save to JSON and reload; resume via captured Claude session id.
  • Packaging: Bundled Python runtime via AgentRuntime; macos/scripts/build-app.sh builds a portable app; dev-setup.sh creates a venv for swift run.

• Bug Fixes

  • Multi‑turn: stable chat session ID across sends; no duplicated user text in prompts; resume without replaying history; workdir paths sanitized and confined to base dir; streamed‑reply history commit scoped to the current turn.
  • Recovery/liveness: sidecar port parse requires a full newline and rechecks liveness before returning; clear stale ports; failed launches terminate the sidecar; WebSocket reconnects replace dead tasks; StreamEvent import fallback preserved, and when streaming is unavailable the backend now emits full TextBlocks so replies still render.
  • Files/payloads: emit file_written only on successful ToolResult; cap flow bodies at 64 KiB and truncate on a UTF‑8 boundary.
  • Capture/UI/layout: install CA trust before starting capture; AppKit text fields for palette/composer; set .regular activation for swift run; traffic card auto‑grows when the inspector opens; conditional min widths and unified card surfaces; two‑line traffic rows with select‑all header; keep in‑memory and persisted flows in sync on delete/clear; HTML preview uses nil baseURL to avoid live fetches, and text copy prefers UTF‑8 when decodable.

^{Written for commit a04add5. Summary will update on new commits. Review in cubic}

Greptile Summary

This PR introduces the full reverse-engineering loop: a Python rae-agent WebSocket sidecar and a SwiftUI three-pane Agent Panel that streams agent events end-to-end. The backend protocol, server, and tests are well-structured, and several bugs from prior rounds are correctly addressed.

• Prompt duplication: AgentSession.send() appends the current user message to history before constructing AgentChatRequest, so build_user_prompt emits the message twice on every single turn.
• Multi-turn file continuity broken: AgentChatRequest is constructed with id: UUID().uuidString on every send() call, creating a brand-new session directory per message and making previously generated files unreachable.

Confidence Score: 3/5

Two bugs in the send path corrupt every multi-turn interaction before the agent produces useful output.

Every message arrives at the model with its text duplicated in the prompt. More critically, each send generates a new random UUID as the session ID, so the agent file output directory is fresh per message — the agent cannot read or edit files it wrote in a previous turn, defeating the multi-turn reverse-engineering workflow.

macos/Sources/ReverseAPI/Agent/AgentSession.swift and backend/rae_agent/prompts.py / session.py need attention before merging.

Important Files Changed

Filename	Overview
backend/rae_agent/session.py	Core agent loop — two issues: user message duplicated in prompt, and every send() creates a new UUID-keyed session dir losing output files between turns.
macos/Sources/ReverseAPI/Agent/AgentSession.swift	Session coordinator — history appended before ChatRequest is built (prompt duplication) and UUID regenerated per send() (breaks multi-turn file continuity).
macos/Sources/ReverseAPI/Agent/AgentSidecar.swift	Python process lifecycle manager — solid overall; minor race in waitForBoundPort where isRunning is tested before reading the stdout buffer.
macos/Sources/ReverseAPI/Agent/AgentClient.swift	WebSocket actor — reconnect on stale task is handled; inner Task in events() is untracked (known from prior review).
macos/Sources/ReverseAPI/Agent/AgentProtocol.swift	Protocol types and AgentEventDecoder — well structured, all event types handled, tests cover decode paths.
backend/rae_agent/server.py	WebSocket server — resolve_base_dir correctly respects RAE_AGENT_WORKDIR; port 0 binding and sentinel print are clean.
backend/rae_agent/prompts.py	System prompt looks good; build_user_prompt receives history already containing the current user message, causing duplication.
macos/Sources/ReverseAPI/UI/AgentPanel.swift	Full SwiftUI agent panel — scroll-to-bottom, ⌘↩ shortcut, and disabled state all handled correctly.

Comments Outside Diff (4)

1. macos/Sources/ReverseAPI/Agent/AgentClient.swift, line 588-614 (link)

   The inner Task spawned inside the AsyncThrowingStream closure is never stored or cancelled. When AgentSession.shutdown() cancels receiverTask, the outer for-try-await loop ends but the inner Task keeps calling task.receive() until it gets a network error or the connection closes. Each call to startReceiver() (which calls events()) creates a new orphaned task. Holding a Task handle and calling .cancel() in the stream's onTermination handler would plug the leak.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: macos/Sources/ReverseAPI/Agent/AgentClient.swift
   Line: 588-614
   
   Comment:
   The inner `Task` spawned inside the `AsyncThrowingStream` closure is never stored or cancelled. When `AgentSession.shutdown()` cancels `receiverTask`, the outer `for-try-await` loop ends but the inner `Task` keeps calling `task.receive()` until it gets a network error or the connection closes. Each call to `startReceiver()` (which calls `events()`) creates a new orphaned task. Holding a `Task` handle and calling `.cancel()` in the stream's `onTermination` handler would plug the leak.
   
   How can I resolve this? If you propose a fix, please make it concise.

2. macos/Sources/ReverseAPI/Agent/AgentSidecar.swift, line 1197-1199 (link)

   Stale port returned after process crash

   launch() guards with if let port { return port } but never checks whether the Python process is still alive. When the sidecar crashes after a successful start, self.port stays set while self.process refers to the dead process. The next call to ensureRunning() (status .failed → enters launch path) returns the stale port, creates a WebSocket task to a dead server, and sets status = .ready. Every subsequent send() then fails, the receiver errors, and status bounces back to .failed — a permanent failure loop with no way to relaunch the Python process short of restarting the app.

   The startReceiver error handler sets status = .failed but never calls sidecar.terminate(), so self.port is never cleared on a spontaneous crash. The fix is to add a liveness check to the early-return guard.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: macos/Sources/ReverseAPI/Agent/AgentSidecar.swift
   Line: 1197-1199
   
   Comment:
   **Stale port returned after process crash**
   
   `launch()` guards with `if let port { return port }` but never checks whether the Python process is still alive. When the sidecar crashes after a successful start, `self.port` stays set while `self.process` refers to the dead process. The next call to `ensureRunning()` (status `.failed` → enters launch path) returns the stale port, creates a WebSocket task to a dead server, and sets `status = .ready`. Every subsequent `send()` then fails, the receiver errors, and `status` bounces back to `.failed` — a permanent failure loop with no way to relaunch the Python process short of restarting the app.
   
   The `startReceiver` error handler sets `status = .failed` but never calls `sidecar.terminate()`, so `self.port` is never cleared on a spontaneous crash. The fix is to add a liveness check to the early-return guard.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

3. macos/Sources/ReverseAPI/Agent/AgentSession.swift, line 1086-1093 (link)

   Current user message duplicated in every LLM prompt

   history.append(...) is called with the current user message before AgentChatRequest is constructed, so history already includes that message. build_user_prompt then emits the message a second time: once as User request: {request.user_message} and again as - user: {trimmed} in the Recent conversation block. Every turn delivers the current message twice to the model, which wastes context and can confuse multi-turn reasoning.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: macos/Sources/ReverseAPI/Agent/AgentSession.swift
   Line: 1086-1093
   
   Comment:
   **Current user message duplicated in every LLM prompt**
   
   `history.append(...)` is called with the current user message _before_ `AgentChatRequest` is constructed, so `history` already includes that message. `build_user_prompt` then emits the message a second time: once as `User request: {request.user_message}` and again as `- user: {trimmed}` in the `Recent conversation` block. Every turn delivers the current message twice to the model, which wastes context and can confuse multi-turn reasoning.
   
   How can I resolve this? If you propose a fix, please make it concise.

4. macos/Sources/ReverseAPI/Agent/AgentSession.swift, line 1087-1093 (link)

   New UUID per send() breaks multi-turn file-system continuity

   id: UUID().uuidString generates a fresh UUID for every message. On the Python side, run_chat uses that UUID as the chat_id to create a brand-new session directory (agent-sessions/<uuid>/out/). Files generated in turn N land in a completely different directory from turn N+1 — the agent can neither Read nor Edit anything it wrote in the previous turn. The Edit tool in allowed_tools is dead in practice after the first message.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: macos/Sources/ReverseAPI/Agent/AgentSession.swift
   Line: 1087-1093
   
   Comment:
   **New UUID per `send()` breaks multi-turn file-system continuity**
   
   `id: UUID().uuidString` generates a fresh UUID for every message. On the Python side, `run_chat` uses that UUID as the `chat_id` to create a brand-new session directory (`agent-sessions/<uuid>/out/`). Files generated in turn N land in a completely different directory from turn N+1 — the agent can neither `Read` nor `Edit` anything it wrote in the previous turn. The `Edit` tool in `allowed_tools` is dead in practice after the first message.
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
macos/Sources/ReverseAPI/Agent/AgentSession.swift:1086-1093
**Current user message duplicated in every LLM prompt**

`history.append(...)` is called with the current user message _before_ `AgentChatRequest` is constructed, so `history` already includes that message. `build_user_prompt` then emits the message a second time: once as `User request: {request.user_message}` and again as `- user: {trimmed}` in the `Recent conversation` block. Every turn delivers the current message twice to the model, which wastes context and can confuse multi-turn reasoning.

### Issue 2 of 3
macos/Sources/ReverseAPI/Agent/AgentSession.swift:1087-1093
**New UUID per `send()` breaks multi-turn file-system continuity**

`id: UUID().uuidString` generates a fresh UUID for every message. On the Python side, `run_chat` uses that UUID as the `chat_id` to create a brand-new session directory (`agent-sessions/<uuid>/out/`). Files generated in turn N land in a completely different directory from turn N+1 — the agent can neither `Read` nor `Edit` anything it wrote in the previous turn. The `Edit` tool in `allowed_tools` is dead in practice after the first message.

### Issue 3 of 3
macos/Sources/ReverseAPI/Agent/AgentSidecar.swift:1252-1262
**Process-liveness check races the stdout buffer in `waitForBoundPort`**

The loop tests `process.isRunning` _before_ calling `buffer.takeLine`. If the Python process prints the `RAE_AGENT_LISTENING:` line and then exits quickly, `isRunning` may already be `false` when the loop ticks. The buffer holds the valid port line but the code throws `SidecarError.processDied` and discards it. Reading the buffer first, then falling through to the liveness check, closes the race window.

_{Reviews (3): Last reviewed commit: "M5: resolve FlowStore conflict markers l..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 386c5e907d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use an executable path instead of a shell command

With the default AgentSession initializer passing "/usr/bin/env python3", this assigns a single path to Process.executableURL; Process does not split shell-style commands, so startup tries to execute a non-existent file at /usr/bin/env python3 and throws before the agent sidecar can launch. Use /usr/bin/env as the executable and put python3 before -m in the arguments, or pass an actual Python binary path.

Useful? React with 👍 / 👎.

[cubic-dev-ai]

10 issues found across 15 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="backend/rae_agent/server.py">

<violation number="1" location="backend/rae_agent/server.py:35">
P1: Validate `request.id` before calling `run_chat`; path traversal sequences can escape `base_dir` when session directories are created.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Validate request.id before calling run_chat; path traversal sequences can escape base_dir when session directories are created.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At backend/rae_agent/server.py, line 35:

<comment>Validate `request.id` before calling `run_chat`; path traversal sequences can escape `base_dir` when session directories are created.</comment>

<file context>
@@ -0,0 +1,76 @@
+        return
+
+    try:
+        request = ChatRequest.from_payload(payload)
+    except ProtocolError as exc:
+        await websocket.send(json.dumps(AgentEvent.error(None, str(exc)).to_dict()))
</file context>

[kind-agent]

⚠️ Error — The test run failed unexpectedly.

Grok 4 Fast is deprecated. xAI recommends switching to Grok 4.3 (https://openrouter.ai/x-ai/grok-4.3)

This is likely a transient issue. You can re-trigger a run from the dashboard.

[kalil0321]

@greptile review

---

Generated by Claude Code

[cubic-dev-ai]

3 issues found across 13 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="backend/rae_agent/server.py">

<violation number="1" location="backend/rae_agent/server.py:35">
P1: Validate `request.id` before calling `run_chat`; path traversal sequences can escape `base_dir` when session directories are created.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[kalil0321]

@greptile review

---

Generated by Claude Code

[cubic-dev-ai]

8 issues found across 11 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="backend/rae_agent/server.py">

<violation number="1" location="backend/rae_agent/server.py:35">
P1: Validate `request.id` before calling `run_chat`; path traversal sequences can escape `base_dir` when session directories are created.</violation>
</file>

<file name="macos/Sources/ReverseAPI/UI/CommandPalette.swift">

<violation number="1" location="macos/Sources/ReverseAPI/UI/CommandPalette.swift:24">
P3: `footer` is implemented but never added to the view hierarchy, so the keyboard-hint UI is dead code and never rendered.</violation>

<violation number="2" location="macos/Sources/ReverseAPI/UI/CommandPalette.swift:309">
P3: The HTTP method/status color mapping is duplicated in `ResultRow` and `PreviewPane`; extract one shared helper to avoid future inconsistency.</violation>
</file>

<file name="macos/Sources/ReverseAPI/UI/InspectorView.swift">

<violation number="1" location="macos/Sources/ReverseAPI/UI/InspectorView.swift:305">
P2: `copyableBody` now misclassifies many readable UTF-8 payloads as binary unless the content type includes `text`.</violation>

<violation number="2" location="macos/Sources/ReverseAPI/UI/InspectorView.swift:360">
P2: Using `flowURL` as the HTML preview base URL can replay network requests for relative resources when viewing captured responses.</violation>
</file>

<file name="macos/Sources/ReverseAPI/UI/AgentPanel.swift">

<violation number="1" location="macos/Sources/ReverseAPI/UI/AgentPanel.swift:546">
P2: Newline handling submits on plain Return, so the multiline composer sends unexpectedly instead of requiring ⌘↵ as indicated by the UI.</violation>
</file>

<file name="macos/Sources/ReverseAPI/UI/Markdown.swift">

<violation number="1" location="macos/Sources/ReverseAPI/UI/Markdown.swift:196">
P2: Trim parsed lines with `.whitespacesAndNewlines`; using `.whitespaces` breaks block detection for CRLF input.</violation>

<violation number="2" location="macos/Sources/ReverseAPI/UI/Markdown.swift:241">
P2: Use `.whitespacesAndNewlines` when trimming fence language to avoid misclassifying unlabeled CRLF fences.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Newline handling submits on plain Return, so the multiline composer sends unexpectedly instead of requiring ⌘↵ as indicated by the UI.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At macos/Sources/ReverseAPI/UI/AgentPanel.swift, line 546:

<comment>Newline handling submits on plain Return, so the multiline composer sends unexpectedly instead of requiring ⌘↵ as indicated by the UI.</comment>

<file context>
@@ -122,211 +163,422 @@ private struct AgentTimeline: View {
+        func textView(_ textView: NSTextView, doCommandBy commandSelector: Selector) -> Bool {
+            if commandSelector == #selector(NSResponder.insertNewline(_:)) {
+                let event = NSApp.currentEvent
+                let isShift = event?.modifierFlags.contains(.shift) ?? false
+                if isShift {
+                    textView.insertNewlineIgnoringFieldEditor(nil)
</file context>

Suggested change

	let isShift = event?.modifierFlags.contains(.shift) ?? false
	if isShift {
	textView.insertNewlineIgnoringFieldEditor(nil)
	return true
	} else {
	onSubmit()
	return true
	}
	let modifiers = event?.modifierFlags ?? []
	if modifiers.contains(.command) {
	onSubmit()
	return true
	}
	textView.insertNewlineIgnoringFieldEditor(nil)
	return true

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="macos/Sources/ReverseAPI/UI/ContentView.swift">

<violation number="1" location="macos/Sources/ReverseAPI/UI/ContentView.swift:28">
P2: The AgentPanel is outside the HSplitView, making it unresizable and failing the 3-pane layout goal.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

4 issues found across 12 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="backend/rae_agent/server.py">

<violation number="1" location="backend/rae_agent/server.py:35">
P1: Validate `request.id` before calling `run_chat`; path traversal sequences can escape `base_dir` when session directories are created.</violation>
</file>

<file name="macos/Sources/ReverseAPI/UI/AgentPanel.swift">

<violation number="1" location="macos/Sources/ReverseAPI/UI/AgentPanel.swift:546">
P2: Newline handling submits on plain Return, so the multiline composer sends unexpectedly instead of requiring ⌘↵ as indicated by the UI.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

You're iterating quickly on this pull request. To help protect your rate limits, cubic has paused automatic reviews on new pushes for now—when you're ready for another review, comment @cubic-dev-ai review.