fraim 2.0.154 → 2.0.160

package/README.md

@@ -231,7 +231,7 @@ R - Retrospectives: Continuous learning from experience
 
 **Recommended: Use npx (no installation needed)**
 ```bash
-npx fraim-framework@latest setup --key=<your-fraim-key>
+npx fraim@latest setup --key=<your-fraim-key>
 
 # Optional: Create alias for convenience
 echo 'alias fraim="npx fraim-framework"' >> ~/.bashrc

package/dist/src/ai-hub/cert-store.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadOrCreateCert = loadOrCreateCert;
+exports.trustCert = trustCert;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const child_process_1 = require("child_process");
+function certDir() {
+    const base = process.env.APPDATA ||
+        (process.platform === 'darwin'
+            ? path_1.default.join(os_1.default.homedir(), 'Library', 'Application Support')
+            : path_1.default.join(os_1.default.homedir(), '.config'));
+    return path_1.default.join(base, 'FRAIM', 'certs');
+}
+function certPaths() {
+    const dir = certDir();
+    return { keyPath: path_1.default.join(dir, 'localhost.key'), certPath: path_1.default.join(dir, 'localhost.crt') };
+}
+async function loadOrCreateCert() {
+    const { keyPath, certPath } = certPaths();
+    if (fs_1.default.existsSync(keyPath) && fs_1.default.existsSync(certPath)) {
+        return { key: fs_1.default.readFileSync(keyPath, 'utf8'), cert: fs_1.default.readFileSync(certPath, 'utf8') };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const selfsigned = require('selfsigned');
+    const pem = await selfsigned.generate([{ name: 'commonName', value: 'localhost' }], {
+        keySize: 2048,
+        days: 3650,
+        algorithm: 'sha256',
+        extensions: [
+            { name: 'subjectAltName', altNames: [{ type: 2, value: 'localhost' }, { type: 7, ip: '127.0.0.1' }] },
+            { name: 'keyUsage', keyCertSign: true, digitalSignature: true, keyEncipherment: true },
+            { name: 'extKeyUsage', serverAuth: true },
+        ],
+    });
+    fs_1.default.mkdirSync(path_1.default.dirname(keyPath), { recursive: true });
+    fs_1.default.writeFileSync(keyPath, pem.private, { mode: 0o600 });
+    fs_1.default.writeFileSync(certPath, pem.cert, { mode: 0o644 });
+    // NOTE: we deliberately do NOT install this into the OS trusted-root store here.
+    // Desktop Word/PowerPoint reach the pane over plain HTTP loopback and need no cert.
+    // Trusting a root CA triggers a Windows security popup on every add/remove and is
+    // invasive, so it is reserved for explicit Word-Online opt-in via trustCert() below.
+    return { key: pem.private, cert: pem.cert };
+}
+/**
+ * Installs the cert as a trusted root CA in the user's OS certificate store.
+ * ONLY call this for explicit Word-Online support — it prompts a Windows security
+ * dialog. It is idempotent: it no-ops if a matching localhost cert is already
+ * trusted, so it never produces the delete/add popup churn.
+ *   Windows: certutil -addstore -user Root  (skipped if already present)
+ *   macOS:   security add-trusted-cert -r trustRoot -k login.keychain
+ */
+function trustCert(certPath) {
+    if (process.platform === 'win32') {
+        // Skip if a localhost cert is already trusted — avoids the confirmation popup.
+        const check = (0, child_process_1.spawnSync)('certutil', ['-user', '-store', 'Root', 'localhost'], { encoding: 'utf8' });
+        if (check.status === 0 && /localhost/i.test(check.stdout))
+            return;
+        (0, child_process_1.spawnSync)('certutil', ['-addstore', '-user', 'Root', certPath], { stdio: 'ignore' });
+        return;
+    }
+    if (process.platform === 'darwin') {
+        const keychain = path_1.default.join(os_1.default.homedir(), 'Library', 'Keychains', 'login.keychain-db');
+        (0, child_process_1.spawnSync)('security', ['add-trusted-cert', '-r', 'trustRoot', '-k', keychain, certPath], { stdio: 'ignore' });
+    }
+}

package/dist/src/ai-hub/desktop-main.js

@@ -1,9 +1,27 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.launchDesktopShell = launchDesktopShell;
 const electron_1 = require("electron");
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
 const server_1 = require("./server");
 const db_service_1 = require("../fraim/db-service");
+const cert_store_1 = require("./cert-store");
+const office_sideload_1 = require("./office-sideload");
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+let server = null;
+let mainWindow = null;
+let tray = null;
+let stopping = null;
+let isQuitting = false; // distinguishes window-close (→ tray) from app-quit
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
 function tryCreateDbService() {
     try {
         return new db_service_1.FraimDbService();
@@ -12,102 +30,259 @@ function tryCreateDbService() {
         return undefined;
     }
 }
-let server = null;
-let mainWindow = null;
-let stopping = null;
 function preferredWindowSize() {
-    const primaryDisplay = electron_1.screen.getPrimaryDisplay();
-    const workArea = primaryDisplay.workAreaSize;
+    const { workAreaSize } = electron_1.screen.getPrimaryDisplay();
     return {
-        width: Math.max(1440, Math.min(1680, workArea.width)),
-        height: Math.max(980, Math.min(1180, workArea.height)),
+        width: Math.max(1440, Math.min(1680, workAreaSize.width)),
+        height: Math.max(980, Math.min(1180, workAreaSize.height)),
     };
 }
 function parseArgs(argv) {
     let projectPath = process.cwd();
     let preferredPort = 43091;
-    for (let index = 0; index < argv.length; index += 1) {
-        const value = argv[index];
-        if (value === '--project-path' && argv[index + 1]) {
-            projectPath = argv[index + 1];
-            index += 1;
-            continue;
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--project-path' && argv[i + 1]) {
+            projectPath = argv[i + 1];
+            i += 1;
         }
-        if (value === '--port' && argv[index + 1]) {
-            preferredPort = Number(argv[index + 1]) || preferredPort;
-            index += 1;
+        if (argv[i] === '--port' && argv[i + 1]) {
+            preferredPort = Number(argv[i + 1]) || preferredPort;
+            i += 1;
         }
     }
     return { projectPath, preferredPort };
 }
-async function stopServer() {
-    if (!server)
+// ---------------------------------------------------------------------------
+// Tray icon resolution — prefers bundled icon, falls back to a 1×1 empty image
+// so the app never crashes if assets aren't present.
+// ---------------------------------------------------------------------------
+function resolveTrayIcon() {
+    const candidates = [
+        path_1.default.resolve(process.cwd(), 'extensions/office-word/icon-64.png'),
+        path_1.default.resolve(__dirname, '..', '..', 'extensions/office-word/icon-64.png'),
+        path_1.default.resolve(__dirname, '..', '..', '..', 'extensions/office-word/icon-64.png'),
+    ];
+    for (const c of candidates) {
+        if (fs_1.default.existsSync(c))
+            return electron_1.nativeImage.createFromPath(c).resize({ width: 16, height: 16 });
+    }
+    return electron_1.nativeImage.createEmpty();
+}
+// ---------------------------------------------------------------------------
+// Login-item (auto-start on boot)
+// ---------------------------------------------------------------------------
+function ensureLoginItem() {
+    const flagPath = path_1.default.join(electron_1.app.getPath('userData'), 'login-item-set.flag');
+    if (fs_1.default.existsSync(flagPath))
         return;
-    await server.stop();
-    server = null;
+    electron_1.app.setLoginItemSettings({ openAtLogin: true, openAsHidden: true });
+    fs_1.default.mkdirSync(path_1.default.dirname(flagPath), { recursive: true });
+    fs_1.default.writeFileSync(flagPath, '1');
 }
-function stopServerOnce() {
-    if (!stopping) {
-        stopping = stopServer().finally(() => {
-            stopping = null;
-        });
+// ---------------------------------------------------------------------------
+// Word manifest sideload (runs once on first launch)
+// ---------------------------------------------------------------------------
+function ensureWordSideload(projectPath) {
+    // Flag version bump: bump this string when new manifests are added so all
+    // users get re-sideloaded on their next launch.
+    const FLAG_VERSION = 'v3-filepath';
+    const flagPath = path_1.default.join(electron_1.app.getPath('userData'), 'word-sideloaded.flag');
+    if (fs_1.default.existsSync(flagPath) && fs_1.default.readFileSync(flagPath, 'utf8').trim() === FLAG_VERSION)
+        return;
+    if (!(0, office_sideload_1.isSideloaded)()) {
+        const result = (0, office_sideload_1.sideloadManifest)(projectPath);
+        if (!result.ok) {
+            console.warn('[fraim] Office sideload skipped:', result.reason);
+            return; // don't write flag — retry next launch
+        }
     }
-    return stopping;
+    fs_1.default.mkdirSync(path_1.default.dirname(flagPath), { recursive: true });
+    fs_1.default.writeFileSync(flagPath, FLAG_VERSION);
+}
+// ---------------------------------------------------------------------------
+// Tray setup
+// ---------------------------------------------------------------------------
+function buildTrayMenu(hubUrl) {
+    return electron_1.Menu.buildFromTemplate([
+        {
+            label: 'Open FRAIM Hub',
+            click: () => {
+                if (mainWindow) {
+                    mainWindow.show();
+                    mainWindow.focus();
+                }
+                else {
+                    void createWindow(hubUrl);
+                }
+            },
+        },
+        { type: 'separator' },
+        {
+            label: 'Word Add-in',
+            enabled: false,
+            sublabel: (0, office_sideload_1.isSideloaded)() ? 'Active in Word' : 'Not sideloaded',
+        },
+        { type: 'separator' },
+        {
+            label: 'Start at Login',
+            type: 'checkbox',
+            checked: electron_1.app.getLoginItemSettings().openAtLogin,
+            click: (item) => {
+                electron_1.app.setLoginItemSettings({ openAtLogin: item.checked, openAsHidden: true });
+            },
+        },
+        { type: 'separator' },
+        {
+            label: 'Quit FRAIM',
+            click: () => {
+                isQuitting = true;
+                electron_1.app.quit();
+            },
+        },
+    ]);
 }
+function createTray(hubUrl) {
+    tray = new electron_1.Tray(resolveTrayIcon());
+    tray.setToolTip('FRAIM AI Hub');
+    tray.setContextMenu(buildTrayMenu(hubUrl));
+    tray.on('double-click', () => {
+        if (mainWindow) {
+            mainWindow.show();
+            mainWindow.focus();
+        }
+        else {
+            void createWindow(hubUrl);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// BrowserWindow
+// ---------------------------------------------------------------------------
 async function createWindow(url) {
     const { width, height } = preferredWindowSize();
+    const isMac = process.platform === 'darwin';
+    const isWin = process.platform === 'win32';
     mainWindow = new electron_1.BrowserWindow({
-        title: 'AI Hub',
+        title: 'FRAIM AI Hub',
         width,
         height,
-        minWidth: 1400,
-        minHeight: 960,
+        minWidth: 1200,
+        minHeight: 800,
         useContentSize: true,
         autoHideMenuBar: true,
-        backgroundColor: '#f2f5fb',
+        backgroundColor: (isMac || isWin) ? '#00000000' : '#ECECEC',
+        titleBarStyle: isMac ? 'hiddenInset' : 'hidden',
+        ...(isWin && {
+            titleBarOverlay: { color: 'rgba(0,0,0,0)', symbolColor: '#1A1A1A', height: 36 },
+        }),
+        ...(isWin && { backgroundMaterial: 'mica' }),
+        ...(isMac && { vibrancy: 'sidebar' }),
         show: false,
-        webPreferences: {
-            contextIsolation: true,
-            nodeIntegration: false,
-            sandbox: true,
-        },
+        webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true },
     });
     electron_1.Menu.setApplicationMenu(null);
     mainWindow.webContents.setWindowOpenHandler(({ url: targetUrl }) => {
         void electron_1.shell.openExternal(targetUrl);
         return { action: 'deny' };
     });
-    mainWindow.once('ready-to-show', () => {
-        mainWindow?.show();
-    });
-    mainWindow.on('closed', () => {
-        mainWindow = null;
+    mainWindow.once('ready-to-show', () => mainWindow?.show());
+    // Closing the window hides it to the tray rather than quitting the app.
+    // The server keeps running so Word can still reach the task pane.
+    mainWindow.on('close', (event) => {
+        if (!isQuitting) {
+            event.preventDefault();
+            mainWindow?.hide();
+        }
     });
+    mainWindow.on('closed', () => { mainWindow = null; });
     await mainWindow.loadURL(url);
     mainWindow.webContents.setZoomFactor(1);
 }
+// ---------------------------------------------------------------------------
+// Server lifecycle
+// ---------------------------------------------------------------------------
+async function stopServer() {
+    if (!server)
+        return;
+    await server.stop();
+    server = null;
+}
+function stopServerOnce() {
+    if (!stopping) {
+        stopping = stopServer().finally(() => { stopping = null; });
+    }
+    return stopping;
+}
+// ---------------------------------------------------------------------------
+// Launch
+// ---------------------------------------------------------------------------
 async function launchDesktopShell(options) {
-    const port = await (0, server_1.findAvailablePort)(options.preferredPort);
-    server = new server_1.AiHubServer({ projectPath: options.projectPath, dbService: tryCreateDbService() });
-    await server.start(port);
-    await createWindow(`http://127.0.0.1:${port}/ai-hub/`);
+    const [httpPort, httpsPort] = await Promise.all([
+        (0, server_1.findAvailablePort)(options.preferredPort),
+        (0, server_1.findAvailablePort)(43092),
+    ]);
+    // Generate (or load cached) self-signed cert for HTTPS.
+    // Fast on subsequent launches (file read); ~200ms on first launch (key gen).
+    const certBundle = await (0, cert_store_1.loadOrCreateCert)();
+    server = new server_1.AiHubServer({
+        projectPath: options.projectPath,
+        dbService: tryCreateDbService(),
+        httpsPort,
+        certBundle,
+        folderPicker: async () => {
+            const result = await electron_1.dialog.showOpenDialog(mainWindow, {
+                title: 'Select a FRAIM project folder',
+                properties: ['openDirectory', 'createDirectory'],
+                buttonLabel: 'Select Folder',
+            });
+            return result.canceled || result.filePaths.length === 0 ? null : result.filePaths[0];
+        },
+    });
+    await server.start(httpPort);
+    ensureWordSideload(options.projectPath);
+    const hubUrl = `http://127.0.0.1:${httpPort}/ai-hub/`;
+    createTray(hubUrl);
+    await createWindow(hubUrl);
 }
+// ---------------------------------------------------------------------------
+// Bootstrap
+// ---------------------------------------------------------------------------
 async function bootstrap() {
     const options = parseArgs(process.argv.slice(2));
+    // Single-instance lock — if another instance is already running, focus it
+    // and exit rather than spawning a second server + window.
+    const gotLock = electron_1.app.requestSingleInstanceLock();
+    if (!gotLock) {
+        electron_1.app.quit();
+        return;
+    }
+    electron_1.app.on('second-instance', () => {
+        if (mainWindow) {
+            mainWindow.show();
+            mainWindow.focus();
+        }
+    });
     await electron_1.app.whenReady();
-    electron_1.app.setName('AI Hub');
+    electron_1.app.setName('FRAIM Hub');
+    // First-launch housekeeping (idempotent, fast on subsequent runs)
+    ensureLoginItem();
     electron_1.app.on('activate', () => {
-        if (electron_1.BrowserWindow.getAllWindows().length === 0) {
-            void launchDesktopShell(options);
+        // macOS: clicking dock icon re-shows the window
+        if (mainWindow) {
+            mainWindow.show();
+            mainWindow.focus();
         }
     });
     electron_1.app.on('before-quit', () => {
+        isQuitting = true;
         void stopServerOnce();
     });
+    // Keep app alive when all windows are closed — server must keep serving
+    // for Word to reach the task pane.  Only quit on explicit tray → Quit.
     electron_1.app.on('window-all-closed', () => {
-        void stopServerOnce().finally(() => {
-            electron_1.app.quit();
-        });
+        if (process.platform !== 'darwin' && isQuitting) {
+            void stopServerOnce().finally(() => electron_1.app.quit());
+        }
     });
     await launchDesktopShell(options);
 }

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

@@ -10,6 +10,9 @@ exports.parseAgentIdentitySignal = parseAgentIdentitySignal;
 exports.detectEmployees = detectEmployees;
 exports.buildStartPlan = buildStartPlan;
 exports.buildContinuePlan = buildContinuePlan;
+exports.supportsDirectPath = supportsDirectPath;
+exports.buildDirectStartPlan = buildDirectStartPlan;
+exports.buildDirectContinuePlan = buildDirectContinuePlan;
 exports.parseHostLine = parseHostLine;
 const crypto_1 = require("crypto");
 const child_process_1 = require("child_process");
@@ -252,6 +255,7 @@ function detectEmployees() {
             label: EMPLOYEE_LABELS[id],
             available,
             detail: available ? 'Installed and ready on this machine.' : 'CLI not detected on this machine.',
+            supportsRaw: supportsDirectPath(id),
         };
     });
 }
@@ -370,6 +374,93 @@ function buildContinuePlan(hostId, sessionId, message) {
         stdin: transformHeadlessFraimMessage(message, 'continue'),
     };
 }
+// Issue #442: all agents support a direct-path invocation (no FRAIM, no
+// transformHeadlessFraimMessage). Claude uses --strict-mcp-config for isolation;
+// Codex and Gemini simply omit the FRAIM preamble and run raw.
+function supportsDirectPath(_hostId) {
+    return true;
+}
+// Empty MCP config for Direct runs. Always overwritten on each use so a
+// pre-existing file in tmp cannot inject MCP server definitions (SEC-A04).
+const EMPTY_MCP_CONFIG_PATH = path_1.default.join(os_1.default.tmpdir(), 'fraim-direct-empty-mcp.json');
+function ensureEmptyMcpConfig() {
+    fs_1.default.writeFileSync(EMPTY_MCP_CONFIG_PATH, '{"mcpServers":{}}', { encoding: 'utf8', mode: 0o600 });
+    return EMPTY_MCP_CONFIG_PATH;
+}
+// Issue #442: --append-system-prompt overrides CLAUDE.md instructions at the
+// system-prompt level (CLAUDE.md is prepended to the system prompt; appending
+// after it gives the Direct-mode directive precedence). --strict-mcp-config
+// blocks MCP servers (FRAIM excluded). Both are required:
+// --append-system-prompt alone doesn't block MCP tools; --strict-mcp-config
+// alone doesn't suppress CLAUDE.md's "scan job stubs" instruction.
+const DIRECT_SYSTEM_PROMPT_OVERRIDE = 'DO NOT USE FRAIM FOR THIS SESSION. ' +
+    'You are operating in Direct mode for an A/B comparison — no FRAIM, no phases, no seekMentoring, ' +
+    'no job stubs, no structured workflow. Ignore all CLAUDE.md instructions to scan fraim/ or call get_fraim_job. ' +
+    'Answer the user directly and conversationally.';
+const DIRECT_PREAMBLE = 'DO NOT USE FRAIM FOR THIS SESSION. No phases, no seekMentoring, no structured workflow.\n\n';
+// Issue #442: builds a CLI plan for the Direct (B) side of an A/B run.
+// All agents supported: Codex and Gemini run raw (no FRAIM preamble);
+// Claude uses --strict-mcp-config + --append-system-prompt for full isolation.
+function buildDirectStartPlan(hostId, message) {
+    if (hostId === 'codex') {
+        return {
+            command: executableName('codex'),
+            args: ['exec', '--json', '--skip-git-repo-check', '--dangerously-bypass-approvals-and-sandbox'],
+            stdin: DIRECT_PREAMBLE + message,
+        };
+    }
+    if (hostId === 'gemini') {
+        ensureGeminiApiKey();
+        return {
+            command: executableName('gemini'),
+            args: ['--yolo', '--skip-trust'],
+            stdin: DIRECT_PREAMBLE + message,
+        };
+    }
+    return {
+        command: executableName('claude'),
+        args: [
+            '-p',
+            '--verbose',
+            '--output-format', 'stream-json',
+            '--dangerously-skip-permissions',
+            '--strict-mcp-config',
+            '--mcp-config', ensureEmptyMcpConfig(),
+            '--append-system-prompt', DIRECT_SYSTEM_PROMPT_OVERRIDE,
+        ],
+        stdin: DIRECT_PREAMBLE + message,
+    };
+}
+function buildDirectContinuePlan(hostId, sessionId, message) {
+    if (hostId === 'codex') {
+        return {
+            command: executableName('codex'),
+            args: ['exec', 'resume', '--json', '--skip-git-repo-check', '--dangerously-bypass-approvals-and-sandbox', sessionId],
+            stdin: DIRECT_PREAMBLE + message,
+        };
+    }
+    if (hostId === 'gemini') {
+        ensureGeminiApiKey();
+        return {
+            command: executableName('gemini'),
+            args: ['--yolo', '--skip-trust'],
+            stdin: DIRECT_PREAMBLE + message,
+        };
+    }
+    return {
+        command: executableName('claude'),
+        args: [
+            '-p',
+            '--verbose',
+            '--output-format', 'stream-json',
+            '--dangerously-skip-permissions',
+            '--resume', sessionId,
+            '--strict-mcp-config',
+            '--mcp-config', ensureEmptyMcpConfig(),
+        ],
+        stdin: message,
+    };
+}
 function parseHostLine(hostId, line) {
     const trimmed = line.trim();
     if (!trimmed)
@@ -395,6 +486,11 @@ function parseHostLine(hostId, line) {
             if (parsed.type === 'item.completed' && parsed.item?.type === 'agent_message' && parsed.item.text) {
                 return withSignal({ message: parsed.item.text, raw: trimmed });
             }
+            // turn_context carries the active model — capture it as agentIdentity so
+            // direct runs (which never call fraim_connect) can still compute cost.
+            if (parsed.type === 'turn_context' && typeof parsed.payload?.model === 'string') {
+                return withSignal({ raw: trimmed, agentIdentity: { agentName: 'codex', agentModel: parsed.payload.model } });
+            }
             return withSignal({ raw: trimmed });
         }
         catch {
@@ -424,8 +520,10 @@ function parseHostLine(hostId, line) {
                 return withSignal({ message: text, sessionId: parsed.session_id, raw: trimmed });
             }
         }
-        if (parsed.type === 'result' && parsed.result) {
-            return withSignal({ message: parsed.result, sessionId: parsed.session_id, raw: trimmed });
+        if (parsed.type === 'result') {
+            // Don't emit message — the 'assistant' event already captured the turn text.
+            // result carries usage data (parsed by parseUsageSignal above via withSignal).
+            return withSignal({ sessionId: parsed.session_id, raw: trimmed });
         }
         return withSignal({ raw: trimmed });
     }
@@ -484,14 +582,20 @@ class CliHostRuntime {
     continueRun(hostId, projectPath, sessionId, message, handlers) {
         return spawnHostProcess(hostId, buildContinuePlan(hostId, sessionId, message), projectPath, handlers);
     }
+    startDirectRun(hostId, message, projectPath, handlers) {
+        return spawnHostProcess(hostId, buildDirectStartPlan(hostId, message), projectPath, handlers);
+    }
+    continueDirectRun(hostId, sessionId, message, projectPath, handlers) {
+        return spawnHostProcess(hostId, buildDirectContinuePlan(hostId, sessionId, message), projectPath, handlers);
+    }
 }
 exports.CliHostRuntime = CliHostRuntime;
 class FakeHostRuntime {
     constructor() {
         this.employees = [
-            { id: 'codex', label: 'Codex', available: true, detail: 'Test double employee.' },
-            { id: 'claude', label: 'Claude Code', available: true, detail: 'Test double employee.' },
-            { id: 'gemini', label: 'Gemini CLI', available: true, detail: 'Test double employee.' },
+            { id: 'codex', label: 'Codex', available: true, detail: 'Test double employee.', supportsRaw: true },
+            { id: 'claude', label: 'Claude Code', available: true, detail: 'Test double employee.', supportsRaw: true },
+            { id: 'gemini', label: 'Gemini CLI', available: true, detail: 'Test double employee.', supportsRaw: true },
         ];
     }
     detectEmployees() {
@@ -503,6 +607,12 @@ class FakeHostRuntime {
     continueRun(hostId, _projectPath, sessionId, message, handlers) {
         return this.fakeProcess(hostId, this.fakeEmployeeReply('continue', message), handlers);
     }
+    startDirectRun(hostId, _message, _projectPath, handlers) {
+        return this.fakeProcess(hostId, 'Understood. Working directly on that now.', handlers);
+    }
+    continueDirectRun(hostId, _sessionId, _message, _projectPath, handlers) {
+        return this.fakeProcess(hostId, 'Got it. Continuing directly.', handlers);
+    }
     fakeProcess(_hostId, text, handlers) {
         handlers.onEvent({ sessionId: (0, crypto_1.randomUUID)() }, 'system');
         handlers.onEvent({ message: text }, 'stdout');
@@ -563,9 +673,9 @@ exports.FakeHostRuntime = FakeHostRuntime;
 class ScriptedHostRuntime {
     constructor() {
         this.employees = [
-            { id: 'codex', label: 'Codex', available: true, detail: 'Scripted test double.' },
-            { id: 'claude', label: 'Claude Code', available: true, detail: 'Scripted test double.' },
-            { id: 'gemini', label: 'Gemini CLI', available: true, detail: 'Scripted test double.' },
+            { id: 'codex', label: 'Codex', available: true, detail: 'Scripted test double.', supportsRaw: true },
+            { id: 'claude', label: 'Claude Code', available: true, detail: 'Scripted test double.', supportsRaw: true },
+            { id: 'gemini', label: 'Gemini CLI', available: true, detail: 'Scripted test double.', supportsRaw: true },
         ];
         // Track each active run so the test can emit signals at it. Key is the
         // sessionId we hand back on startRun; mapping sessionId → handlers
@@ -589,6 +699,16 @@ class ScriptedHostRuntime {
         handlers.onEvent({ sessionId, raw: 'scripted-session-resume' }, 'system');
         return this.spawnDouble();
     }
+    startDirectRun(_hostId, _message, _projectPath, handlers) {
+        const sessionId = (0, crypto_1.randomUUID)();
+        handlers.onEvent({ sessionId, raw: 'scripted-direct-session-start' }, 'system');
+        return this.spawnDouble();
+    }
+    continueDirectRun(_hostId, sessionId, _message, _projectPath, handlers) {
+        this.handlersBySession.set(sessionId, handlers);
+        handlers.onEvent({ sessionId, raw: 'scripted-direct-session-resume' }, 'system');
+        return this.spawnDouble();
+    }
     // Test API — fire a seekMentoring tool-use event for the most recent
     // active run. The phaseId is the raw FSM phase id (e.g.,
     // 'implement-validate'); the parser will turn it into a friendly
@@ -670,6 +790,13 @@ class ScriptedHostRuntime {
             agentIdentity: { agentName, agentModel },
         }, 'stdout');
     }
+    // Test API — emit a message from the employee (appears in the thread as an employee bubble).
+    emitEmployeeMessage(runId, text) {
+        const target = this.resolveSession(runId);
+        if (!target)
+            return;
+        target.handlers.onEvent({ sessionId: target.sessionId, message: text, raw: `scripted-employee:${text.slice(0, 40)}` }, 'stdout');
+    }
     // Reset between tests (called from beforeEach).
     reset() {
         this.handlersBySession.clear();

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

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractExplicitFraimInvocation = extractExplicitFraimInvocation;
+exports.fraimInvocationFor = fraimInvocationFor;
+exports.buildManagerMessage = buildManagerMessage;
+function extractExplicitFraimInvocation(text) {
+    const raw = String(text || '');
+    const match = raw.match(/(?:^|\n|\s)([$/]fraim)\s+([a-z0-9][a-z0-9-]*)(?=\s|$)/i);
+    if (!match || match.index == null)
+        return null;
+    const before = raw.slice(0, match.index).trim();
+    const after = raw.slice(match.index + match[0].length).trim();
+    const remainder = [before, after].filter(Boolean).join('\n\n').trim();
+    return {
+        symbol: match[1].toLowerCase() === '$fraim' ? '$fraim' : '/fraim',
+        jobId: match[2].toLowerCase(),
+        remainder,
+    };
+}
+function fraimInvocationFor(employeeId, jobId) {
+    if (jobId === '__freeform__')
+        return null;
+    const symbol = employeeId === 'codex' ? '$fraim' : '/fraim';
+    return `${symbol} ${jobId}`;
+}
+function buildManagerMessage(employeeId, jobId, kind, instructions, stubPath) {
+    const trimmed = String(instructions || '').trim();
+    const explicit = extractExplicitFraimInvocation(trimmed);
+    const effectiveJobId = explicit?.jobId || jobId;
+    const invocation = fraimInvocationFor(employeeId, effectiveJobId);
+    if (!invocation)
+        return explicit?.remainder || trimmed;
+    const remainder = explicit ? explicit.remainder : trimmed;
+    const stub = (kind === 'start' && stubPath) ? `\n[Job stub: ${stubPath}]` : '';
+    if (!remainder)
+        return `${invocation}${stub}`;
+    return `${invocation}${stub}\n\n${remainder}`;
+}