feat(flow-v2): autonomous research digest, agentic RAG, graph query, FlowIsland, Chrome extension

[Sekoya88]

Summary

• Research Digest: daily arXiv + HuggingFace paper ingestion, AI scoring, Obsidian export, Qdrant embed-as-knowledge (fixed uuid5 point IDs)
• Agentic RAG: Qdrant hybrid search (BM25 + dense, RRF fusion), toggled per-agent via Knowledge & Tools tab
• Knowledge Graph: natural-language query with keyword fallback, cascade node delete (edges + Qdrant), graph path detection
• Chrome Extension: full digest feed with status tabs, delete, mark read, SSE live log, Run Now
• FlowIsland: macOS notch client with live skill graph, agent picker, knowledge tab
• Bug fixes: gpt-5.4-mini typo → gpt-4o-mini (5 occurrences), key_insights list→str coercion, export-obsidian 400 removed, summarize crash fixed
• Docs: rewritten README, new experience.md setup guide, removed stale Electron menubar app

Test plan

• docker compose up --build — all services start cleanly
• Register + onboarding flow on web
• Research → Run now → papers appear in Unread tab
• Select paper → Summarize (no crash)
• Select paper → Export to Obsidian (requires vault mount)
• Select paper → Embed as Knowledge → Qdrant dashboard shows points
• Graph → Query → returns results for any topic
• Graph → click node → delete button removes node + edges
• Research → paper card → BookX (vault delete) + Trash (DB delete)
• Agents → Config → Knowledge & Tools tab → toggles persist
• Chrome extension → loads, shows digest, delete/mark-read work

---

Summary by cubic

Ships Flow v2: autonomous research digest, hybrid agentic RAG, natural-language graph query, and two new clients — FlowIsland (macOS notch) and a Chrome extension — with live observability, MCP tool integration, and a refreshed skills experience. Includes CI cleanups (ruff/ESLint) and minor naming fixes.

• New Features

  • Research Digest: fetch from arXiv + HuggingFace, relevance scoring, TLDRs, Obsidian export, Qdrant embed, global SSE events, web dashboard with unread/read tabs.
  • Agentic RAG: Qdrant hybrid search (BM25 + dense, RRF fusion) toggled per agent under Knowledge & Tools.
  • Knowledge Graph: NL query with keyword fallback, cascade delete, paper nodes, related-paper edges, path detection.
  • Observability: workspace-wide live stream on Logs → Live; per-agent live panel (subagents, todos); local discovery + WS channel for desktop.
  • FlowIsland (macOS): notch UI with agent picker, live skill graph, event feed, and quick links.
  • Chrome Extension: quick capture (text/image), selection tooltip, agent launcher, full digest feed, Run Now, MCP vault status.
  • MCP: server registry (CRUD, ping, list/invoke tools), standalone SSE service; settings page to manage servers.
  • Skills: category-first hub, Create Skill sheet (Template/Vibe/Library), vibe-modify streaming; seed scripts for templates and memory.
  • Autonomy: SkillBandit (Thompson sampling), GenomeEvolver loop, MetaCognition journal/skill scoring, workflow snapshot export.
  • Infra/Docs: deterministic Qdrant IDs, .env.example additions, docker-compose services (mcp, minio), new experience guide; ruff/ESLint fixes and formatting.

• Migration

  • Copy .env.example → .env, set at least FLOW_OPENAI_API_KEY and FLOW_JWT_SECRET; optionally set Obsidian/GitHub/MinIO vars.
  • Run make update to build/start api, worker, web, mcp, minio, apply migrations, and seed data.
  • Ensure an Obsidian vault is available: set FLOW_OBSIDIAN_MODE and mount FLOW_OBSIDIAN_VAULT_PATH (filesystem) or configure API/cloud.
  • Optional: build the Chrome extension (apps/chrome-extension) and load unpacked; open apps/mac/FlowIsland.xcodeproj in Xcode to run FlowIsland.

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

[cursor]

Stale comment

Pull request risk assessment

Risk level: High
Code review: Required
Automation decision: Do not approve

This assessment is based only on the diff (18f1f41…f69ee85, 153 files, +15,459 / −401). PR title/description claims are not used as evidence.

Why High (not Medium-High)

Area	Evidence
Blast radius	Touches API core (LangGraph nodes, skill loader, digest graph), persistence, queue worker, new HTTP routes, web app shell/pages, Docker infra, and two new client surfaces (Chrome extension + macOS FlowIsland).
Data model	Eight Alembic migrations (0020–0027): new tables (rl_episodes, metacog_journal, mcp_servers, digest_papers, …), agent_versions lineage columns, kg_nodes CHECK rewrite, data backfill (0024), and a UNIQUE constraint on existing digest_papers (0027) — rollback and deploy ordering matter.
Security / auth	New MCP service (JWT-validated tools, GitHub Actions dispatch, web research, Obsidian/MinIO vault paths); Chrome extension JWT in chrome.storage.local; /set-token?t= writes JWT to localStorage; observability WebSocket accepts connections without auth (see inline). User-supplied MCP server URLs in API (/api/v1/mcp/servers) expand SSRF surface.
Prompts / agent behavior	Large skill template seed (+771 lines), MCP research-digest prompt, planner skill-loading refactor — material model-behavior change.
Infra	New mcp + minio services, vault volume mounts, host ports 18001 / 19000.
CI	API — lint (ruff) and Web — ESLint + type-check are failing on this PR; API — pytest skipped after lint failure.

Actions taken

• Not approved (High risk — automation never approves High).
• Reviewers: No additional GitHub collaborators on Sekoya88/Flow besides the author; no reviewer requests were added (would not satisfy meaningful independent review).
• CODEOWNERS: None configured on this repository.

Merge guidance

1. Fix CI (ruff + web lint/type-check) and ensure pytest runs green.
2. Human review focused on: migration deploy plan, MCP/SSRF boundaries, WebSocket + extension auth, and production secrets handling.
3. Treat Agentic Security Review (if enabled) as blocking for auth/MCP surfaces.

---

Cursor automation — risk assessment from diff evidence only.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Security (High): This endpoint calls websocket.accept() without JWT/workspace checks (comment acknowledges “for now”). Any client that can reach the API can subscribe to agent_events:{agent_id} and receive MetaCog/skill/RL events. Gate on the same auth pattern as other agent routes (query-token or session) before merge to any shared/staging/prod network.

[cursor]

Security: JWT is taken from the t query parameter and persisted to localStorage. That pattern leaks via browser history, Referer, and server/proxy logs. Prefer a short-lived exchange code, POST body, or fragment-only handoff; align with how SSE already passes tokens today and track hardening in a follow-up if intentional for the extension.

[cursor]

Migration risk: Adding UNIQUE (workspace_id, title) on digest_papers will fail if duplicate titles already exist in any environment. Run a pre-migration dedupe check in staging before production deploy.

[cubic-dev-ai]

9 issues found across 153 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="apps/chrome-extension/src/background/service-worker.ts">

<violation number="1" location="apps/chrome-extension/src/background/service-worker.ts:37">
P2: Check the ingest API response status before showing success; otherwise failed saves can be reported as successful.</violation>
</file>

<file name="apps/mac/FlowIsland/AgentDiscovery.swift">

<violation number="1" location="apps/mac/FlowIsland/AgentDiscovery.swift:24">
P2: Overlapping `/active-agents` poll responses can be applied out of order, causing stale agent reconnections.</violation>
</file>

<file name="apps/chrome-extension/src/content/inject.ts">

<violation number="1" location="apps/chrome-extension/src/content/inject.ts:22">
P2: For a fixed-position tooltip, adding `window.scrollY` to `rect.top` misplaces the tooltip on scrolled pages. Use viewport coordinates directly.</violation>
</file>

<file name="apps/web/src/app/set-token/page.tsx">

<violation number="1" location="apps/web/src/app/set-token/page.tsx:9">
P1: Avoid accepting auth tokens via query parameters; this exposes credentials in URL-based logs/history before redirect. Use a non-URL channel (e.g., POST or hash fragment exchange) for token handoff.</violation>
</file>

<file name="apps/chrome-extension/src/popup/App.tsx">

<violation number="1" location="apps/chrome-extension/src/popup/App.tsx:43">
P2: Guard against users with no workspaces before rendering workspace-dependent tabs; passing an empty `workspaceId` can break downstream API requests.</violation>
</file>

<file name="apps/chrome-extension/src/popup/components/QuickCapture.tsx">

<violation number="1" location="apps/chrome-extension/src/popup/components/QuickCapture.tsx:27">
P2: Revoke the previous preview URL before replacing `pastedImage`; otherwise repeated pastes leak object URLs.</violation>
</file>

<file name="apps/chrome-extension/src/popup/components/AgentLauncher.tsx">

<violation number="1" location="apps/chrome-extension/src/popup/components/AgentLauncher.tsx:17">
P2: Do not swallow `listAgents` errors; this currently shows a false "No agents in this workspace" state when loading fails.</violation>
</file>

<file name="apps/chrome-extension/src/lib/mcp-client.ts">

<violation number="1" location="apps/chrome-extension/src/lib/mcp-client.ts:28">
P1: `listMCPTools` is wired to a backend endpoint that currently crashes (`repo.pool` vs `repo._pool`), so this new call will fail at runtime instead of returning tools.</violation>
</file>

<file name="apps/chrome-extension/src/lib/flow-api.ts">

<violation number="1" location="apps/chrome-extension/src/lib/flow-api.ts:22">
P2: `flowFetch` incorrectly spreads `init.headers`; `Headers` inputs can be lost. Normalize with `new Headers(...)` (or `Object.fromEntries`) before merging.</violation>
</file>

<sub>Note: This PR contains a large number of files. cubic only reviews up to 100 files per PR, so some files may not have been reviewed. cubic prioritizes the most important files to review.
On a pro plan you can use ultrareview for larger PRs.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Avoid accepting auth tokens via query parameters; this exposes credentials in URL-based logs/history before redirect. Use a non-URL channel (e.g., POST or hash fragment exchange) for token handoff.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/web/src/app/set-token/page.tsx, line 9:

<comment>Avoid accepting auth tokens via query parameters; this exposes credentials in URL-based logs/history before redirect. Use a non-URL channel (e.g., POST or hash fragment exchange) for token handoff.</comment>

<file context>
@@ -0,0 +1,18 @@
+  const router = useRouter();
+  const params = useSearchParams();
+  useEffect(() => {
+    const t = params.get("t");
+    if (t) localStorage.setItem("flow_token", t);
+    router.replace("/dashboard");
</file context>

[cubic-dev-ai]

P1: listMCPTools is wired to a backend endpoint that currently crashes (repo.pool vs repo._pool), so this new call will fail at runtime instead of returning tools.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/chrome-extension/src/lib/mcp-client.ts, line 28:

<comment>`listMCPTools` is wired to a backend endpoint that currently crashes (`repo.pool` vs `repo._pool`), so this new call will fail at runtime instead of returning tools.</comment>

<file context>
@@ -0,0 +1,29 @@
+}
+
+export async function listMCPTools(serverId: string): Promise<MCPTool[]> {
+  return flowFetch(`/api/v1/mcp/servers/${serverId}/tools`);
+}
</file context>

[cubic-dev-ai]

P2: Check the ingest API response status before showing success; otherwise failed saves can be reported as successful.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/chrome-extension/src/background/service-worker.ts, line 37:

<comment>Check the ingest API response status before showing success; otherwise failed saves can be reported as successful.</comment>

<file context>
@@ -0,0 +1,65 @@
+    const wsId = me.workspaces?.[0]?.id;
+    if (!wsId) return;
+
+    await fetch(`${baseUrl}/api/v1/knowledge/ingest`, {
+      method: "POST",
+      headers: {
</file context>

Suggested change

	await fetch(`${baseUrl}/api/v1/knowledge/ingest`, {
	method: "POST",
	headers: {
	"Content-Type": "application/json",
	Authorization: `Bearer ${token}`,
	},
	body: JSON.stringify({
	workspace_id: wsId,
	title: tab?.title ?? "Web capture",
	content: text,
	source_url: tab?.url,
	}),
	});
	const ingestRes = await fetch(`${baseUrl}/api/v1/knowledge/ingest`, {
	method: "POST",
	headers: {
	"Content-Type": "application/json",
	Authorization: `Bearer ${token}`,
	},
	body: JSON.stringify({
	workspace_id: wsId,
	title: tab?.title ?? "Web capture",
	content: text,
	source_url: tab?.url,
	}),
	});
	if (!ingestRes.ok) throw new Error("ingest");

[cubic-dev-ai]

P2: Overlapping /active-agents poll responses can be applied out of order, causing stale agent reconnections.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mac/FlowIsland/AgentDiscovery.swift, line 24:

<comment>Overlapping `/active-agents` poll responses can be applied out of order, causing stale agent reconnections.</comment>

<file context>
@@ -0,0 +1,64 @@
+
+    private func poll() {
+        guard let url = URL(string: "\(API_BASE)/active-agents") else { return }
+        URLSession.shared.dataTask(with: url) { [weak self] data, _, _ in
+            guard let self, let data else { return }
+            guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
</file context>

[cubic-dev-ai]

P2: For a fixed-position tooltip, adding window.scrollY to rect.top misplaces the tooltip on scrolled pages. Use viewport coordinates directly.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/chrome-extension/src/content/inject.ts, line 22:

<comment>For a fixed-position tooltip, adding `window.scrollY` to `rect.top` misplaces the tooltip on scrolled pages. Use viewport coordinates directly.</comment>

<file context>
@@ -0,0 +1,49 @@
+  tooltip.textContent = "📥 Save to Flow";
+  Object.assign(tooltip.style, {
+    position: "fixed",
+    top: `${rect.top + window.scrollY - 36}px`,
+    left: `${rect.left + rect.width / 2}px`,
+    transform: "translateX(-50%)",
</file context>

[cubic-dev-ai]

P2: Guard against users with no workspaces before rendering workspace-dependent tabs; passing an empty workspaceId can break downstream API requests.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/chrome-extension/src/popup/App.tsx, line 43:

<comment>Guard against users with no workspaces before rendering workspace-dependent tabs; passing an empty `workspaceId` can break downstream API requests.</comment>

<file context>
@@ -0,0 +1,79 @@
+  if (!checked) return null;
+  if (!me) return <LoginGate onLogin={() => getMe().then(setMe)} />;
+
+  const wsId = me.workspaces[0]?.id ?? "";
+  const wsName = me.workspaces[0]?.name ?? "workspace";
+
</file context>

[cubic-dev-ai]

P2: Revoke the previous preview URL before replacing pastedImage; otherwise repeated pastes leak object URLs.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/chrome-extension/src/popup/components/QuickCapture.tsx, line 27:

<comment>Revoke the previous preview URL before replacing `pastedImage`; otherwise repeated pastes leak object URLs.</comment>

<file context>
@@ -0,0 +1,107 @@
+    const blob = item.getAsFile();
+    if (!blob) return;
+    const preview = URL.createObjectURL(blob);
+    setPastedImage({ blob, preview });
+  }
+
</file context>

[cubic-dev-ai]

P2: Do not swallow listAgents errors; this currently shows a false "No agents in this workspace" state when loading fails.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/chrome-extension/src/popup/components/AgentLauncher.tsx, line 17:

<comment>Do not swallow `listAgents` errors; this currently shows a false "No agents in this workspace" state when loading fails.</comment>

<file context>
@@ -0,0 +1,89 @@
+        setAgents(a);
+        if (a[0]) setSelectedId(a[0].id);
+      })
+      .catch(() => null)
+      .finally(() => setLoaded(true));
+  }, [workspaceId]);
</file context>

[cubic-dev-ai]

P2: flowFetch incorrectly spreads init.headers; Headers inputs can be lost. Normalize with new Headers(...) (or Object.fromEntries) before merging.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/chrome-extension/src/lib/flow-api.ts, line 22:

<comment>`flowFetch` incorrectly spreads `init.headers`; `Headers` inputs can be lost. Normalize with `new Headers(...)` (or `Object.fromEntries`) before merging.</comment>

<file context>
@@ -0,0 +1,123 @@
+    headers: {
+      "Content-Type": "application/json",
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      ...init?.headers,
+    },
+  });
</file context>

[cursor]

Pull request risk assessment (updated)

Risk level: High
Code review: Required
Automation decision: Do not approve

Re-evaluated on synchronize to f6815eb (diff base 18f1f41…f6815eb, 153 files, +15,397 / −401). Assessment uses diff evidence only.

Delta since last automation run (f69ee85 → f6815eb)

Change	Impact on risk
fix(ci): resolve all ruff and ESLint failures — 31 files, mostly lint/refactor in digest graph, routes, tests	CI posture improved (ruff + web lint now green; pytest passing on latest run)
No rollback of migrations, MCP service, extension, FlowIsland, or auth surfaces	Blast radius unchanged

Risk classification unchanged: High. Green CI reduces merge friction but does not shrink operational or security exposure.

Why High

Area	Evidence
Blast radius	Core API (LangGraph nodes.py, digest graph, skill loader), queue worker, 8 Alembic migrations (0020–0027 incl. backfill 0024, UNIQUE on digest_papers 0027), new services/mcp + MinIO in docker-compose.yml, large web surfaces (research, skills, MCP settings), Chrome extension, macOS FlowIsland
Security / auth	User-configurable MCP server URLs with server-side httpx ping/invoke (SSRF class); observability WebSocket accepts without auth; /set-token?t= JWT handoff via query string; extension stores JWT in chrome.storage.local; MCP tools include GitHub Actions dispatch
Prompts / agent behavior	Large skill_templates.py seed, MCP research-digest prompt, planner/skill-loading changes in graph nodes
Data model	New tables (mcp_servers, digest_papers, RL/metacog/bandit) + constraint changes on existing data

Actions taken

• Not approved (High risk — automation never self-approves High).
• Reviewers: Sekoya88/Flow has no other collaborators besides the author; no reviewer requests added.
• CODEOWNERS: None configured.
• Prior approval: None from this automation; no dismissal required.
• Slack: Summary could not be posted — no Slack webhook or Slack MCP is configured in this agent environment.

Merge guidance

1. Human review before merge: migrations deploy order, MCP/SSRF boundaries, WebSocket + extension auth, production secrets.
2. Fix remaining correctness issues flagged by cubic (e.g. repo.pool vs repo._pool on MCP tools route).
3. Treat Agentic Security Review as blocking where enabled.

---

Cursor automation — risk assessment from diff evidence only.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Security (High-risk surface): This endpoint calls websocket.accept() without JWT or workspace checks. Any client that can reach the API can subscribe to agent_events:{agent_id} for arbitrary UUIDs — acceptable only behind strict network isolation; gate before production.

[cursor]

Security: JWT in query string (?t=) is logged in proxies, browser history, and Referer. Prefer POST body, hash-fragment exchange, or extension-only chrome.runtime messaging for token handoff.

[cursor]

Correctness: repo.pool will raise at runtime — other routes in this file use repo._pool. Same bug cubic flagged for the Chrome extension MCP tools call.

[cubic-dev-ai]

1 issue found across 31 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="services/api/flow/interfaces/http/routes/mcp.py">

<violation number="1" location="services/api/flow/interfaces/http/routes/mcp.py:151">
P1: AttributeError at runtime: repo.pool does not exist on FlowRepository. The private attribute is repo._pool (with underscore). This will raise an AttributeError when list_mcp_server_tools is called.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: AttributeError at runtime: repo.pool does not exist on FlowRepository. The private attribute is repo._pool (with underscore). This will raise an AttributeError when list_mcp_server_tools is called.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At services/api/flow/interfaces/http/routes/mcp.py, line 151:

<comment>AttributeError at runtime: repo.pool does not exist on FlowRepository. The private attribute is repo._pool (with underscore). This will raise an AttributeError when list_mcp_server_tools is called.</comment>

<file context>
@@ -161,9 +148,7 @@ async def list_mcp_server_tools(
-    row = await repo.pool.fetchrow(
-        "SELECT * FROM mcp_servers WHERE id = $1", server_id
-    )
+    row = await repo.pool.fetchrow("SELECT * FROM mcp_servers WHERE id = $1", server_id)
     if not row:
         raise HTTPException(status_code=404, detail="MCP server not found")
</file context>

Suggested change

	row = await repo.pool.fetchrow("SELECT * FROM mcp_servers WHERE id = $1", server_id)
	row = await repo._pool.fetchrow("SELECT * FROM mcp_servers WHERE id = $1", server_id)