fraim-framework 2.0.161 → 2.0.162

package/dist/src/ai-hub/managed-browser.js

@@ -0,0 +1,269 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ManagedBrowser = void 0;
+exports.browserExecutableCandidates = browserExecutableCandidates;
+exports.resolveBrowserExecutable = resolveBrowserExecutable;
+exports.buildBrowserLaunchArgs = buildBrowserLaunchArgs;
+exports.buildBrowserContextNote = buildBrowserContextNote;
+exports.defaultBrowserProfileDir = defaultBrowserProfileDir;
+exports.probeCdpEndpoint = probeCdpEndpoint;
+/**
+ * #521 — FRAIM-managed persistent browser.
+ *
+ * Problem: the Hub runs each agent turn as a one-shot process (`claude -p …`).
+ * When a turn ends, that process exits and any browser it launched (a child of
+ * the agent) is torn down — so "open a browser, I'll log in, then continue"
+ * never works: the window dies at the turn boundary before the manager can log in.
+ *
+ * Fix: FRAIM owns ONE long-lived Chromium browser (Chrome or Edge) launched with
+ * a remote-debugging port and a persistent profile. It outlives agent turns.
+ * Agents `connectOverCDP` to it instead of launching their own, so the session —
+ * including a manual login — survives across turns. One shared browser, one
+ * persistent profile; concurrency isolation is intentionally NOT solved here
+ * (see persistent-browser-session skill) to keep this simple.
+ */
+const child_process_1 = require("child_process");
+const http_1 = __importDefault(require("http"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+/**
+ * Known install locations for Chrome and Edge per platform. Pure + injectable so
+ * resolution can be unit-tested without the browsers actually being installed.
+ */
+function browserExecutableCandidates(platform = process.platform, env = process.env) {
+    if (platform === 'win32') {
+        const pf = env['ProgramFiles'] || 'C:\\Program Files';
+        const pf86 = env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)';
+        const local = env['LOCALAPPDATA']
+            || path_1.default.join(env['USERPROFILE'] || 'C:\\Users\\Default', 'AppData', 'Local');
+        return {
+            chrome: [
+                path_1.default.join(pf, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+                path_1.default.join(pf86, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+                path_1.default.join(local, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+            ],
+            msedge: [
+                path_1.default.join(pf86, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+                path_1.default.join(pf, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+            ],
+        };
+    }
+    if (platform === 'darwin') {
+        return {
+            chrome: ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'],
+            msedge: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+        };
+    }
+    // linux + anything else
+    return {
+        chrome: ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser'],
+        msedge: ['/usr/bin/microsoft-edge', '/usr/bin/microsoft-edge-stable'],
+    };
+}
+/**
+ * Resolve a Chromium executable. Returns null when neither Chrome nor Edge is
+ * found (caller surfaces a clear "install Chrome or Edge" error).
+ */
+function resolveBrowserExecutable(opts = {}) {
+    const exists = opts.exists || ((p) => fs_1.default.existsSync(p));
+    if (opts.explicitPath) {
+        if (exists(opts.explicitPath)) {
+            const channel = /edge|msedge/i.test(opts.explicitPath) ? 'msedge' : 'chrome';
+            return { channel, path: opts.explicitPath };
+        }
+        return null;
+    }
+    const candidates = browserExecutableCandidates(opts.platform, opts.env);
+    const order = opts.channel === 'msedge'
+        ? ['msedge', 'chrome']
+        : ['chrome', 'msedge']; // 'chrome' and 'auto' both prefer Chrome first
+    for (const channel of order) {
+        for (const candidate of candidates[channel]) {
+            if (exists(candidate))
+                return { channel, path: candidate };
+        }
+    }
+    return null;
+}
+/**
+ * Args that put Chrome/Edge into a debuggable, prompt-free, persistent-profile
+ * state. Headed (no --headless) so the manager can log in by hand.
+ */
+function buildBrowserLaunchArgs(opts) {
+    return [
+        `--remote-debugging-port=${opts.port}`,
+        `--user-data-dir=${opts.userDataDir}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+        // Required so Playwright's CDP WebSocket handshake is accepted by recent Chromium.
+        '--remote-allow-origins=*',
+        'about:blank',
+    ];
+}
+/**
+ * The runtime guidance the Hub injects into an agent's start message so it uses
+ * the shared browser. This is intentionally a UI/Hub-layer injection — it is NOT
+ * baked into any registry job or skill. Returns '' when the shared browser is not
+ * available (so the note only appears when there is something to connect to).
+ */
+function buildBrowserContextNote(cdpEndpoint, hubBaseUrl) {
+    if (!cdpEndpoint || !hubBaseUrl)
+        return '';
+    return [
+        '',
+        '[FRAIM shared browser] A persistent shared browser is available — use it instead of launching your own.',
+        `Before using a browser, ensure it is running: \`POST ${hubBaseUrl}/api/ai-hub/browser/start\` (idempotent — it reuses the running browser, or relaunches it if it was closed).`,
+        `Then drive the shared browser at ${cdpEndpoint}: your Playwright/browser tools are pointed at it on supported agents; if your tools would otherwise open their own browser, connect to the shared one with \`connectOverCDP("${cdpEndpoint}")\` and reuse its existing context/tab.`,
+        'Never close the shared browser or sign me out. If a site needs login, open it there and ask me to log in — the session persists to your next turn.',
+    ].join('\n');
+}
+/** Default persistent profile directory — sandboxed from the user's daily browser. */
+function defaultBrowserProfileDir(env = process.env) {
+    const home = env['FRAIM_HOME'] || os_1.default.homedir();
+    return path_1.default.join(home, '.fraim', 'browser-profile');
+}
+/**
+ * Probe a CDP endpoint's /json/version. Resolves true only when it answers with a
+ * Chromium DevTools payload. Uses node http (no fetch dependency).
+ */
+function probeCdpEndpoint(endpoint, timeoutMs = 1500) {
+    return new Promise((resolve) => {
+        let url;
+        try {
+            url = new URL('/json/version', endpoint);
+        }
+        catch {
+            resolve(false);
+            return;
+        }
+        const req = http_1.default.get(url, { timeout: timeoutMs }, (res) => {
+            let body = '';
+            res.on('data', (chunk) => { body += chunk.toString(); });
+            res.on('end', () => {
+                try {
+                    const data = JSON.parse(body);
+                    resolve(!!(data && (data.webSocketDebuggerUrl || data.Browser)));
+                }
+                catch {
+                    resolve(false);
+                }
+            });
+        });
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+    });
+}
+const DEFAULT_PORT = 9222;
+/**
+ * Owns the lifecycle of the single shared browser. start() is idempotent — it
+ * reuses an already-running browser on the port — so multiple callers (and Hub
+ * restarts) converge on one instance.
+ */
+class ManagedBrowser {
+    constructor(opts = {}) {
+        this.child = null;
+        this.ownsProcess = false;
+        this.resolved = null;
+        this.opts = opts;
+        this.channel = opts.channel || 'auto';
+        this.port = opts.port || DEFAULT_PORT;
+        this.host = opts.host || '127.0.0.1';
+        this.userDataDir = opts.userDataDir || defaultBrowserProfileDir(opts.env);
+    }
+    cdpEndpoint() {
+        return `http://${this.host}:${this.port}`;
+    }
+    probe() {
+        return this.opts.probeFn ? this.opts.probeFn(this.cdpEndpoint()) : probeCdpEndpoint(this.cdpEndpoint());
+    }
+    /** Live check — does a Chromium CDP endpoint answer on the port right now. */
+    isRunning() {
+        return this.probe();
+    }
+    async start() {
+        // 1. Reuse a browser already listening on the port (idempotent across callers
+        //    and Hub restarts; also lets the manager pre-launch their own).
+        if (await this.probe()) {
+            return { endpoint: this.cdpEndpoint(), reused: true, executable: this.resolved?.path || null, channel: this.resolved?.channel || null };
+        }
+        // Already spawned by us but not yet reachable → just wait for it.
+        if (this.child && this.ownsProcess) {
+            await this.waitForRunning();
+            return { endpoint: this.cdpEndpoint(), reused: false, executable: this.resolved?.path || null, channel: this.resolved?.channel || null };
+        }
+        // 2. Resolve the executable.
+        const exe = resolveBrowserExecutable({
+            channel: this.channel,
+            explicitPath: this.opts.explicitPath,
+            platform: this.opts.platform,
+            env: this.opts.env,
+            exists: this.opts.exists,
+        });
+        if (!exe) {
+            throw new Error('No Chrome or Edge found. Install Google Chrome or Microsoft Edge, or set FRAIM_BROWSER_PATH to a Chromium executable.');
+        }
+        this.resolved = exe;
+        // 3. Ensure the profile dir exists, then spawn the browser long-lived. It is a
+        //    child of the Hub server (so it dies with the Hub) but NOT of any agent
+        //    turn — that is the whole point.
+        try {
+            if (!this.opts.exists)
+                fs_1.default.mkdirSync(this.userDataDir, { recursive: true });
+        }
+        catch { /* best-effort; browser will create it */ }
+        const args = buildBrowserLaunchArgs({ port: this.port, userDataDir: this.userDataDir });
+        const spawnFn = this.opts.spawnFn || ((c, a, o) => (0, child_process_1.spawn)(c, a, o));
+        const child = spawnFn(exe.path, args, { stdio: 'ignore', windowsHide: false });
+        this.child = child;
+        this.ownsProcess = true;
+        if (typeof child.on === 'function') {
+            child.on('exit', () => {
+                if (this.child === child) {
+                    this.child = null;
+                    this.ownsProcess = false;
+                }
+            });
+        }
+        // 4. Wait until the CDP endpoint is reachable before returning the endpoint.
+        await this.waitForRunning();
+        return { endpoint: this.cdpEndpoint(), reused: false, executable: exe.path, channel: exe.channel };
+    }
+    async waitForRunning() {
+        const timeoutMs = this.opts.waitTimeoutMs ?? 15000;
+        const intervalMs = this.opts.waitIntervalMs ?? 250;
+        const startedAt = Date.now();
+        for (;;) {
+            if (await this.probe())
+                return;
+            if (Date.now() - startedAt > timeoutMs) {
+                throw new Error(`Browser did not become reachable on ${this.cdpEndpoint()} within ${timeoutMs}ms.`);
+            }
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+    }
+    /** Kill the browser only if WE launched it — never a browser the manager owns. */
+    stop() {
+        if (this.child && this.ownsProcess && typeof this.child.kill === 'function') {
+            try {
+                this.child.kill();
+            }
+            catch { /* ignore */ }
+        }
+        this.child = null;
+        this.ownsProcess = false;
+    }
+    status() {
+        return {
+            ownsProcess: this.ownsProcess,
+            endpoint: this.cdpEndpoint(),
+            channel: this.resolved?.channel || this.channel,
+            userDataDir: this.userDataDir,
+            executable: this.resolved?.path || null,
+        };
+    }
+}
+exports.ManagedBrowser = ManagedBrowser;

package/dist/src/ai-hub/manager-turns.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractExplicitFraimInvocation = extractExplicitFraimInvocation;
 exports.fraimInvocationFor = fraimInvocationFor;
+exports.buildCommunicationStyleNote = buildCommunicationStyleNote;
 exports.buildManagerMessage = buildManagerMessage;
 function extractExplicitFraimInvocation(text) {
     const raw = String(text || '');
@@ -23,6 +24,18 @@ function fraimInvocationFor(employeeId, jobId) {
     const symbol = employeeId === 'codex' ? '$fraim' : '/fraim';
     return `${symbol} ${jobId}`;
 }
+// #521: a Hub-injected communication-style note so the employee's messages to the
+// manager stay about the JOB and its outcomes — not the FRAIM machinery (seeking
+// mentoring, tool calls, git, phase switches). The structured signals (the
+// tracker's seekMentoring events, the review_handoff) still flow as tool calls
+// behind the scenes, so this only shapes the human-facing prose. Injected at the
+// Hub layer — it never edits the jobs.
+function buildCommunicationStyleNote() {
+    return [
+        '',
+        '[How to talk to me] In your messages to me, report ONLY on the job and its outcome — what you found, what you changed, the decisions you made, blockers, and what you need from me. Do NOT narrate the FRAIM machinery: don\'t announce that you are talking to FRAIM, asking your mentor, following the process, moving between phases, or calling tools (git, playwright, etc.). I can see the raw tool activity separately if I want it. Keep your updates short and about the work, not the process.',
+    ].join('\n');
+}
 function buildManagerMessage(employeeId, jobId, kind, instructions, stubPath) {
     const trimmed = String(instructions || '').trim();
     const explicit = extractExplicitFraimInvocation(trimmed);

package/dist/src/ai-hub/preferences.js

@@ -14,6 +14,7 @@ const defaultPreferences = (projectPath) => ({
     employeeId: DEFAULT_EMPLOYEE,
     categoryId: DEFAULT_CATEGORY,
     recentJobIds: [],
+    recentJobInstructions: {},
     personaKey: null,
 });
 class AiHubPreferencesStore {
@@ -31,6 +32,9 @@ class AiHubPreferencesStore {
                 employeeId: (raw.employeeId === 'claude' || raw.employeeId === 'codex') ? raw.employeeId : DEFAULT_EMPLOYEE,
                 categoryId: typeof raw.categoryId === 'string' && raw.categoryId.length > 0 ? raw.categoryId : DEFAULT_CATEGORY,
                 recentJobIds: Array.isArray(raw.recentJobIds) ? raw.recentJobIds.filter((value) => typeof value === 'string') : [],
+                recentJobInstructions: (typeof raw.recentJobInstructions === 'object' && raw.recentJobInstructions !== null && !Array.isArray(raw.recentJobInstructions))
+                    ? raw.recentJobInstructions
+                    : {},
                 personaKey: typeof raw.personaKey === 'string' ? raw.personaKey : null,
                 apiKey: typeof raw.apiKey === 'string' && raw.apiKey.length > 0 ? raw.apiKey : undefined,
             };
@@ -43,13 +47,18 @@ class AiHubPreferencesStore {
         fs_1.default.mkdirSync(path_1.default.dirname(this.stateFilePath), { recursive: true });
         fs_1.default.writeFileSync(this.stateFilePath, JSON.stringify(preferences, null, 2));
     }
-    remember(preferences, jobId) {
+    remember(preferences, jobId, instructions) {
         const recentJobIds = jobId
             ? [jobId, ...preferences.recentJobIds.filter((value) => value !== jobId)].slice(0, 8)
             : preferences.recentJobIds.slice(0, 8);
+        const recentJobInstructions = { ...preferences.recentJobInstructions };
+        if (jobId && instructions) {
+            recentJobInstructions[jobId] = instructions.slice(0, 500);
+        }
         const next = {
             ...preferences,
             recentJobIds,
+            recentJobInstructions,
         };
         this.save(next);
         return next;