@thoughtflow/core 0.2.1 → 0.3.0

package/dist/tools/workspace/browser-session-pool.js

@@ -0,0 +1,302 @@
+"use strict";
+/**
+ * BrowserSessionPool — manages multiple headless browser sessions with
+ * isolated pages, console logs, and network activity per session.
+ *
+ * Auto-cleans up sessions after 5 minutes of inactivity.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browserPool = exports.BrowserSessionPool = void 0;
+const SESSION_TTL_MS = 5 * 60 * 1000; // 5 minutes
+class BrowserSessionPool {
+    sessions = new Map();
+    cleanupTimer = null;
+    /** Create or retrieve a session. If sessionId is empty, creates a new one. */
+    async getOrCreate(sessionId) {
+        if (sessionId && this.sessions.has(sessionId)) {
+            const session = this.sessions.get(sessionId);
+            session.lastActivity = Date.now();
+            const activePage = session.pages.find(p => p.id === session.activePageId);
+            if (activePage && !activePage.page.isClosed()) {
+                return { sessionId, page: activePage.page };
+            }
+            // Active page closed — create a new one
+            return this.newPage(sessionId);
+        }
+        // Create new session
+        const id = sessionId ?? `br_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { chromium } = require("playwright");
+        const browser = await chromium.launch({ headless: true });
+        const page = await browser.newPage();
+        const browserPage = {
+            id: `pg_${Date.now()}`,
+            page,
+            consoleEntries: [],
+            networkEntries: [],
+            netIdx: 0,
+        };
+        const session = {
+            browser,
+            pages: [browserPage],
+            activePageId: browserPage.id,
+            initUrl: "",
+            createdAt: Date.now(),
+            lastActivity: Date.now(),
+        };
+        this.sessions.set(id, session);
+        this.startCleanup();
+        // Attach listeners
+        this.attachListeners(browserPage);
+        return { sessionId: id, page };
+    }
+    /** Navigate the active page of a session. */
+    async getPage(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return null;
+        session.lastActivity = Date.now();
+        const active = session.pages.find(p => p.id === session.activePageId);
+        if (!active || active.page.isClosed())
+            return null;
+        return active.page;
+    }
+    /** Open a new tab in an existing session. */
+    async newPage(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            throw new Error(`Session ${sessionId} not found`);
+        session.lastActivity = Date.now();
+        const page = await session.browser.newPage();
+        const browserPage = {
+            id: `pg_${Date.now()}`,
+            page,
+            consoleEntries: [],
+            networkEntries: [],
+            netIdx: 0,
+        };
+        session.pages.push(browserPage);
+        session.activePageId = browserPage.id;
+        this.attachListeners(browserPage);
+        return { sessionId, page };
+    }
+    /** Switch active tab. */
+    switchPage(sessionId, pageId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return false;
+        const exists = session.pages.find(p => p.id === pageId && !p.page.isClosed());
+        if (!exists)
+            return false;
+        session.activePageId = pageId;
+        session.lastActivity = Date.now();
+        return true;
+    }
+    /** Close a tab (or the active one if pageId omitted). */
+    async closePage(sessionId, pageId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return false;
+        session.lastActivity = Date.now();
+        const targetId = pageId ?? session.activePageId;
+        const idx = session.pages.findIndex(p => p.id === targetId);
+        if (idx === -1)
+            return false;
+        const bp = session.pages[idx];
+        await bp.page.close().catch(() => { });
+        session.pages.splice(idx, 1);
+        // If we closed the active page, switch to another
+        if (session.activePageId === targetId && session.pages.length > 0) {
+            session.activePageId = session.pages[0].id;
+        }
+        return true;
+    }
+    /** Destroy a session completely. */
+    async destroy(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        for (const bp of session.pages) {
+            await bp.page.close().catch(() => { });
+        }
+        await session.browser.close().catch(() => { });
+        this.sessions.delete(sessionId);
+    }
+    /** Destroy all sessions. */
+    async destroyAll() {
+        let count = 0;
+        for (const [id, session] of this.sessions) {
+            for (const bp of session.pages) {
+                await bp.page.close().catch(() => { });
+            }
+            await session.browser.close().catch(() => { });
+            this.sessions.delete(id);
+            count++;
+        }
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        return count;
+    }
+    /** Set the initial navigation URL for a session. */
+    setInitUrl(sessionId, url) {
+        const session = this.sessions.get(sessionId);
+        if (session && !session.initUrl) {
+            session.initUrl = url;
+        }
+    }
+    /** List all active sessions with metadata. */
+    list() {
+        const now = Date.now();
+        const result = [];
+        for (const [id, session] of this.sessions) {
+            const active = session.pages.find(p => p.id === session.activePageId && !p.page.isClosed());
+            const idleMs = now - session.lastActivity;
+            result.push({
+                sessionId: id,
+                initUrl: session.initUrl || "(no navigation yet)",
+                currentUrl: active ? active.page.url() : "(closed)",
+                pageCount: session.pages.filter(p => !p.page.isClosed()).length,
+                activePageId: session.activePageId,
+                createdAt: session.createdAt,
+                lastActivity: session.lastActivity,
+                status: idleMs > 60_000 ? "idle" : "active",
+            });
+        }
+        return result;
+    }
+    /** Get console logs for active page. */
+    getConsole(sessionId) {
+        return this.getActivePageData(sessionId)?.consoleEntries ?? [];
+    }
+    /** Get network entries for active page. */
+    getNetwork(sessionId) {
+        return this.getActivePageData(sessionId)?.networkEntries ?? [];
+    }
+    /** Clear console logs for active page. */
+    clearConsole(sessionId) {
+        const bp = this.getActivePageData(sessionId);
+        if (bp)
+            bp.consoleEntries = [];
+    }
+    /** Clear network entries for active page. */
+    clearNetwork(sessionId) {
+        const bp = this.getActivePageData(sessionId);
+        if (bp)
+            bp.networkEntries = [];
+    }
+    /** Cache a screenshot base64 string for the session. */
+    cacheScreenshot(sessionId, base64) {
+        const session = this.sessions.get(sessionId);
+        if (session)
+            session.cachedScreenshot = base64;
+    }
+    /** Get cached screenshot base64 string. */
+    getCachedScreenshot(sessionId) {
+        const session = this.sessions.get(sessionId);
+        return session.cachedScreenshot ?? null;
+    }
+    /** List all open tabs in a session. */
+    listPages(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return [];
+        return session.pages
+            .filter(p => !p.page.isClosed())
+            .map(p => ({
+            id: p.id,
+            url: p.page.url(),
+            title: "", // Will be filled by caller if needed
+            active: p.id === session.activePageId,
+        }));
+    }
+    // ── Private ────────────────────────────────────────────────────────────────
+    getActivePageData(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return null;
+        session.lastActivity = Date.now();
+        return session.pages.find(p => p.id === session.activePageId && !p.page.isClosed()) ?? null;
+    }
+    attachListeners(bp) {
+        // Console
+        bp.page.on("console", (msg) => {
+            bp.consoleEntries.push({
+                type: msg.type(),
+                text: msg.text(),
+                location: msg.location().url ? `${msg.location().url}:${msg.location().lineNumber}` : "",
+                timestamp: Date.now(),
+            });
+        });
+        // Network
+        const timings = new Map();
+        bp.page.on("request", (req) => {
+            const idx = ++bp.netIdx;
+            timings.set(req.url() + req.method(), Date.now());
+            let reqBody;
+            try {
+                reqBody = req.postData() ?? undefined;
+            }
+            catch { }
+            bp.networkEntries.push({
+                idx, method: req.method(), url: req.url(),
+                reqHeaders: req.headers(),
+                reqBody, timestamp: Date.now(),
+            });
+        });
+        bp.page.on("response", async (resp) => {
+            const key = resp.url() + resp.request().method();
+            const start = timings.get(key);
+            const duration = start ? Date.now() - start : undefined;
+            let entry = bp.networkEntries.find(e => e.url === resp.url() && e.method === resp.request().method());
+            if (!entry) {
+                entry = { idx: ++bp.netIdx, method: resp.request().method(), url: resp.url(), timestamp: Date.now() };
+                bp.networkEntries.push(entry);
+            }
+            entry.status = resp.status();
+            entry.statusText = resp.statusText();
+            entry.duration = duration;
+            entry.resHeaders = resp.headers();
+            try {
+                const ct = resp.headers()["content-type"] ?? "";
+                if (ct.includes("json") || ct.includes("text") || ct.includes("xml") || ct.includes("javascript")) {
+                    entry.resBody = await resp.text().catch(() => undefined);
+                }
+            }
+            catch { }
+        });
+        bp.page.on("requestfailed", (req) => {
+            bp.networkEntries.push({
+                idx: ++bp.netIdx, method: req.method(), url: req.url(),
+                error: req.failure()?.errorText ?? "Unknown error",
+                reqHeaders: req.headers(),
+                timestamp: Date.now(),
+            });
+        });
+    }
+    startCleanup() {
+        if (this.cleanupTimer)
+            return;
+        this.cleanupTimer = setInterval(() => {
+            const now = Date.now();
+            for (const [id, session] of this.sessions) {
+                if (now - session.lastActivity > SESSION_TTL_MS) {
+                    for (const bp of session.pages) {
+                        bp.page.close().catch(() => { });
+                    }
+                    session.browser.close().catch(() => { });
+                    this.sessions.delete(id);
+                }
+            }
+            if (this.sessions.size === 0 && this.cleanupTimer) {
+                clearInterval(this.cleanupTimer);
+                this.cleanupTimer = null;
+            }
+        }, 60_000).unref();
+    }
+}
+exports.BrowserSessionPool = BrowserSessionPool;
+/** Singleton instance */
+exports.browserPool = new BrowserSessionPool();
+//# sourceMappingURL=browser-session-pool.js.map

package/dist/tools/workspace/browser-session-pool.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thoughtflow/core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "TypeScript framework for building autonomous AI agents with LLM tool-calling, streaming, plugins, skills, and workspace automation",
   "license": "MIT",
   "repository": {
@@ -24,6 +24,7 @@
   "types": "dist/index.d.ts",
   "files": [
     "dist/**/*",
+    "skills/thoughtflow-mcp/SKILL.md",
     "README.md",
     "LICENSE"
   ],
@@ -64,5 +65,8 @@
     "ts-jest": "^29.2.6",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.3"
+  },
+  "bin": {
+    "thoughtflow-mcp": "dist/bin/mcp-server.js"
   }
 }

package/skills/thoughtflow-mcp/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: thoughtflow-mcp
+description: "Use when thoughtflow MCP tools (mcp__thoughtflow__*) are available. 100+ coding tools: file ops, git, search, code analysis, refactoring, testing, planning, vision browser. Use tool_search first to discover the right tool and its parameters — never call an unfamiliar tool without checking its schema. The tool list is compressed; call tool_search with a natural language query to get full parameter details."
+version: 0.1.0
+author: thoughtflow
+license: MIT
+metadata:
+  hermes:
+    tags: [thoughtflow, mcp, tools, coding, autonomous]
+    related_skills: []
+---
+
+# thoughtflow MCP — 100+ Coding Tools
+
+## Overview
+
+thoughtflow exposes 100+ battle-tested coding tools through MCP. Every tool is
+prefixed `mcp__thoughtflow__`. The tool list is **compressed by default** —
+you see names + one-liners, not full schemas. Use `tool_search` to discover
+tools and their parameters on demand.
+
+## When to Use
+
+This skill activates automatically when `mcp__thoughtflow__tool_search` is in
+your tool list. It guides you to use thoughtflow tools efficiently.
+
+**Use thoughtflow tools when you need:**
+- File operations — prefer Hermes built-in tools (`read_file`, `write_file`, `patch`, `search_files`) for speed and session integration. Use MCP workspace tools only for workspace-relative paths or bulk operations.
+- Git operations (status, diff, commit, branch, log)
+- Codebase analysis (search, dependency graphs, impact, cross-references)
+- Code review & quality (neural review, complexity, duplication, security scan)
+- Refactoring (rename, extract, move, split, organize imports)
+- Testing (generate unit/integration tests, fix failures, find gaps)
+- Documentation (generate README, API docs, ADR, diagrams)
+- Planning (problem decomposition, task breakdown, estimation)
+- Terminal commands (shell execution with workspace awareness)
+- Visual page analysis (screenshot + vision model inspection)
+
+**Don't use thoughtflow tools for:**
+- Simple one-liner questions that don't need code access
+- Tasks that Hermes's built-in tools handle better (memory, session_search, etc.)
+
+## Core Workflow: tool_search → execute
+
+**NEVER call a thoughtflow tool without knowing its parameters.** The compressed
+tool list hides input schemas. Always discover first:
+
+```
+1. tool_search("read and write text files")     → find the right tool
+2. read the parameter schemas in the response   → learn what params it needs
+3. mcp__thoughtflow__readFile({path: "..."})    → call with correct params
+```
+
+### tool_search query patterns
+
+| Describe what you want | Example query |
+|---|---|
+| By domain | `"workspace tools"`, `"testing tools"`, `"codebase tools"` |
+| By action | `"search for code"`, `"create a migration"`, `"review code quality"` |
+| By file type | `"generate TypeScript tests"`, `"refactor imports"` |
+
+### If tool_search returns "no tools found"
+
+Broaden the query or search by domain. Every tool belongs to one of these
+domains: workspace, codebase, neural, planning, refactor, testing, quality,
+docs, devops, database, memory.
+
+## Domain Quick Reference
+
+| Domain | What it provides | Key tools |
+|---|---|---|
+| **workspace** | File I/O, terminal, git, browser, HTTP, search | `readFile`, `writeFile`, `grep`, `terminalRun`, `git`, `patchFile` |
+| **codebase** | Repository intelligence | `codebaseSearch`, `codebaseIndex`, `codebaseImpact`, `codebaseFlow` |
+| **neural** | LLM-powered analysis | `neuralReview`, `neuralExplain`, `neuralDebug`, `neuralSecurity` |
+| **planning** | Task decomposition | `solveComplex`, `pmBreakdown`, `pmEstimate`, `problemTree` |
+| **refactor** | Code transformation | `refactorRename`, `refactorExtract`, `refactorImports` |
+| **testing** | Test automation | `testGenUnit`, `testFix`, `testGap`, `testFuzz` |
+| **quality** | Code metrics | `qualityComplexity`, `qualityCoverage`, `qualityDuplication` |
+| **docs** | Documentation | `docGenReadme`, `docGenApi`, `docGenDiagrams` |
+| **devops** | CI/CD & infra | `ciWorkflow`, `deployCheck`, `dockerOptimize` |
+| **database** | DB operations | `dbMigration`, `dbDiagram` |
+| **vision** | Visual analysis | `visionBrowser` — screenshot + vision LLM |
+
+## Efficient Usage Patterns
+
+These patterns mirror real thoughtflow development workflows. Follow them exactly.
+
+### Before ANY code change (mandatory)
+```
+1. grep or codebaseSearch to understand current state
+2. codebaseImpact({files: ["src/target.ts"]}) to check blast radius
+3. Make changes
+4. neuralReview({paths: ["src/"]}) to catch issues
+5. runTsc or terminalRun("bun run build && bun run test") to verify
+```
+
+### Investigating a bug
+```
+1. neuralDebug({error: "...", files: ["src/"]}) → AI-powered root cause
+2. grep({pattern: "offending_symbol"}) → find all occurrences
+3. codebaseFlow({entryFile: "src/app.ts", function: "brokenFn"}) → trace call path
+4. Fix
+5. testGenUnit({target: "src/fixed.ts"}) → add regression test
+```
+
+### Refactoring (rename/extract/move)
+```
+1. refactorRename({oldName: "oldFn", newName: "newFn", paths: ["src/"]})
+2. refactorImports({paths: ["src/"]}) → clean up
+3. qualityComplexity({paths: ["src/"]}) → verify improvement
+4. bun run build && bun run test
+```
+
+### Adding a new feature
+```
+1. solveComplex({problem: "Add pagination to the user list endpoint"})
+   → returns task tree with dependencies
+2. Implement in dependency order (problemTree for progress tracking)
+3. testGenIntegration({target: "src/new-feature.ts"})
+4. neuralReview + build + test
+```
+
+### Visual testing a web page
+```
+1. browser({action:"open"}) → save sessionId
+2. browser({action:"navigate", sessionId, url:"http://localhost:3000"})
+3. browser({action:"snapshot", sessionId}) → find [ref=eN] elements
+4. browser({action:"click", sessionId, selector:"e4"})
+5. browser({action:"vision", sessionId, prompt:"Does the login form look correct?"})
+6. browser({action:"console", sessionId}) → check for JS errors
+7. browser({action:"network", sessionId}) → check for failed API calls
+8. browser({action:"close", sessionId}) when done
+```
+
+### Pre-commit quality gate
+```
+1. qualityComplexity → no function > 10 complexity
+2. qualityDuplication → no new duplications
+3. qualityTypes → no new `any` types
+4. testGap → no uncovered paths
+5. neuralSecurity → no hardcoded secrets
+6. bun run build && bun run test → green
+
+
+## Vision Browser
+
+`visionBrowser` takes a URL or HTML and a prompt, renders it with headless
+Chromium, and analyzes the screenshot with a vision model:
+
+```
+visionBrowser({
+  url: "https://example.com",
+  prompt: "Is the login button visible? What color is the header?",
+  captureConsole: true,
+  captureNetwork: true,
+})
+```
+
+Console logs and network activity (with full request/response headers and body)
+can be captured by adding `captureConsole: true` and `captureNetwork: true`.
+
+Works with any OpenAI-compatible vision model. Requires Playwright
+(`npm install playwright`).
+
+## Interactive Browser (Stateful)
+
+The `browser` tool maintains state across calls via `sessionId`. Each session
+is an isolated Chromium process. **ALWAYS follow this flow — never improvise:**
+
+```
+// 1. Open a session
+browser({action: "open"})
+→ {"sessionId": "br_abc123"}
+
+// 2. Navigate
+browser({action: "navigate", sessionId: "br_abc123", url: "https://example.com"})
+→ {"title": "Page Title", "url": "https://example.com"}
+
+// 3. Inspect the DOM (accessibility tree, compact, with [ref=eN] markers)
+browser({action: "snapshot", sessionId: "br_abc123"})
+→ - link "Home" [ref=e1]
+  - button "Get Started" [ref=e2]
+  - textbox "Search..." [ref=e3]
+
+// 4. Interact using [ref=eN] from snapshot
+browser({action: "click", sessionId: "br_abc123", selector: "e2"})
+browser({action: "type", sessionId: "br_abc123", selector: "e3", text: "hello"})
+
+// 5. Check console for JS errors
+browser({action: "console", sessionId: "br_abc123"})
+→ [error] TypeError: ... — app.js:42
+
+// 6. Check network for failed API calls
+browser({action: "network", sessionId: "br_abc123"})
+→ ✗ POST /api/auth → 401 (567ms)
+
+// 7. Visual check
+browser({action: "screenshot", sessionId: "br_abc123"})
+→ screenshot:base64:iVBOR...
+
+// 8. Close when done
+browser({action: "close", sessionId: "br_abc123"})
+```
+
+**Key rules:**
+- Save `sessionId` from `open` — use it for ALL subsequent calls
+- Use `snapshot` not `get_dom` — the accessibility tree is compact and has `[ref=eN]`
+- `console` and `network` auto-accumulate from session start
+- Sessions auto-expire after 5 min — don't leave them open
+- Use `list` to see all active sessions
+
+## Safety Rules
+
+### Never do these without user approval:
+- `git checkout <file>` or `git reset --hard` that discards uncommitted changes
+- `git push --force`
+- `rm -rf`, recursive deletion, wiping directories
+- `DROP TABLE`, `TRUNCATE`, `DELETE FROM` without WHERE
+
+### Before any destructive operation:
+1. Backup first: `cp file.ts file.ts.bak` or `git stash`
+2. Check impact: `codebaseImpact` on the target
+3. Ask: "Can I undo this in 30 seconds?"
+4. If no → STOP and ask the user
+
+## Planning + TODO workflow
+
+Always decompose complex tasks into a Hermes TODO list:
+
+```
+1. mcp__thoughtflow__solveComplex({problem: "..."}) → dependency tree
+2. Translate into Hermes `todo` items in dependency order
+3. Mark complete as you go — the TODO is your source of truth
+4. Report progress from the TODO list, not from memory
+```
+
+## Common Pitfalls
+
+1. **Calling tools without tool_search first.** The compressed list doesn't show
+   parameters. You'll get schema errors. Always `tool_search("what you want")` first.
+
+2. **Using Hermes built-in tools when thoughtflow has better ones.** The built-in
+   `read_file` is for reading into context; `mcp__thoughtflow__readFile` works on
+   the workspace project. Use thoughtflow tools for project operations.
+
+3. **Forgetting the `mcp__thoughtflow__` prefix.** All thoughtflow tools are
+   prefixed. `readFile` ≠ `mcp__thoughtflow__readFile`.
+
+4. **Not checking allowedPaths.** If a file operation fails, the path might be
+   outside the configured workspace sandbox. Check `thoughtflow.config.json`.
+
+5. **Calling `open` multiple times for the same task.** Each `open` creates a
+   new session. Save the `sessionId` and reuse it for all browser actions.
+
+6. **Using `get_dom` instead of `snapshot`.** `get_dom` returns raw HTML
+   (potentially huge). `snapshot` returns a compact accessibility tree with
+   `[ref=eN]` markers that `click` and `type` understand directly.
+
+7. **Not checking console/network after interactions.** JS errors and failed
+   API calls are auto-captured. Check `console` and `network` after
+   clicks/navigation — they often reveal the root cause of UI issues.
+
+## Installation & Updates
+
+### One-command install
+
+```bash
+npx @thoughtflow/mcp-server install-skill
+```
+
+Copies the skill to `~/.hermes/skills/thoughtflow-mcp/SKILL.md`.
+Use `--target` for custom locations:
+
+```bash
+npx @thoughtflow/mcp-server install-skill --target ~/.agents/skills/
+```
+
+### Manual install
+
+```bash
+cp skills/thoughtflow-mcp/SKILL.md ~/.hermes/skills/thoughtflow-mcp/
+```
+
+### Updating
+
+Re-run `install-skill` after pulling the latest thoughtflow — it overwrites the old skill file. Start a new Hermes session to pick up changes.
+
+## Verification Checklist
+
+- [ ] `hermes mcp test thoughtflow` returns "Connected" with tools listed
+- [ ] `tool_search("workspace tools")` returns file/git/terminal tools with schemas
+- [ ] `mcp__thoughtflow__readFile({path: "README.md"})` reads a file successfully
+- [ ] In chat, LLM calls `tool_search` before calling unfamiliar tools
+- [ ] Vision browser works when configured: `visionBrowser({url: "...", prompt: "..."})`