@scira/cli 0.1.0

package/dist/ui/ink/hooks/use-feed.js

@@ -0,0 +1,69 @@
+import { useCallback, useRef, useState } from "react";
+export function useFeed() {
+    const [feed, setFeed] = useState([]);
+    const feedRef = useRef([]);
+    const pushFeed = useCallback((item) => {
+        setFeed((f) => { const next = [...f, item]; feedRef.current = next; return next; });
+    }, []);
+    const appendText = useCallback((delta) => {
+        setFeed((f) => {
+            const next = [...f];
+            const last = next.at(-1);
+            if (last?.kind === "text") {
+                next[next.length - 1] = { ...last, text: last.text + delta };
+            }
+            else {
+                next.push({ kind: "text", text: delta });
+            }
+            feedRef.current = next;
+            return next;
+        });
+    }, []);
+    const appendReasoning = useCallback((delta) => {
+        setFeed((f) => {
+            const next = [...f];
+            const last = next.at(-1);
+            if (last?.kind === "reasoning" && last.durationMs === undefined) {
+                next[next.length - 1] = { ...last, text: last.text + delta };
+            }
+            else {
+                next.push({ kind: "reasoning", text: delta, startedAt: Date.now() });
+            }
+            feedRef.current = next;
+            return next;
+        });
+    }, []);
+    const finishReasoning = useCallback(() => {
+        setFeed((f) => {
+            let changed = false;
+            const ended = Date.now();
+            const next = f.map((it) => {
+                if (it.kind === "reasoning" && it.durationMs === undefined) {
+                    changed = true;
+                    const startedAt = it.startedAt ?? ended;
+                    return { ...it, durationMs: ended - startedAt };
+                }
+                return it;
+            });
+            if (!changed)
+                return f;
+            feedRef.current = next;
+            return next;
+        });
+    }, []);
+    const markToolDone = useCallback((toolCallId, status, result) => {
+        setFeed((f) => {
+            const next = [...f];
+            for (let i = next.length - 1; i >= 0; i--) {
+                const item = next[i];
+                if (item.kind === "tool" && item.status === "running" && (item.toolCallId === toolCallId || !toolCallId)) {
+                    next[i] = { ...item, status, result };
+                    break;
+                }
+            }
+            feedRef.current = next;
+            return next;
+        });
+    }, []);
+    return { feed, setFeed, feedRef, pushFeed, appendText, appendReasoning, finishReasoning, markToolDone };
+}

package/dist/ui/ink/hooks/use-keyboard.js

@@ -0,0 +1,315 @@
+import { useRef } from "react";
+import { useInput } from "ink";
+export function useKeyboard(o) {
+    const { screen, setNotice, exit } = o;
+    const { text: inputText, setText: setInputText, cursorPos, setCursorPos, history: inputHistory, historyIndex, setHistoryIndex } = o.input;
+    const { approvalPending, setApprovalPending, menu, setMenu, applyMenuSelection, helpOpen, setHelpOpen, mcpOpen, setMcpOpen } = o.dialogs;
+    const { activeSuggestions, activeSuggestionKind, commandMenuIndex, setCommandMenuIndex, acceptActiveSuggestion } = o.suggestions;
+    const { setScrollOffset, contentRows, maxScrollOffset, pendingRerun, setPendingRerun, busy, stopTurn, submitChat, toggleAllGroups, toggleFocusedGroup, focusPrevGroup, focusNextGroup, unfocusGroup, hasFocusedGroup } = o.chat;
+    const { sessionsModalOpen, setSessionsModalOpen, sessionsModalIdx, setSessionsModalIdx, sessions, deleteSession, selectedIdx, setSelectedIdx, setHeroHidden, openRun, submitHome } = o.home;
+    const deleteArmedRef = useRef(null);
+    const editInput = (char, key) => {
+        const deleteWordBefore = () => {
+            const match = inputText.slice(0, cursorPos).match(/\S+\s*$/u);
+            const toDelete = match ? match[0].length : 0;
+            setInputText((c) => c.slice(0, cursorPos - toDelete) + c.slice(cursorPos));
+            setCursorPos((p) => Math.max(0, p - toDelete));
+        };
+        if (key.leftArrow) {
+            setCursorPos((p) => Math.max(0, p - 1));
+            return true;
+        }
+        if (key.rightArrow) {
+            setCursorPos((p) => Math.min(inputText.length, p + 1));
+            return true;
+        }
+        if (key.delete && !key.backspace) {
+            if (cursorPos < inputText.length) {
+                setInputText((c) => c.slice(0, cursorPos) + c.slice(cursorPos + 1));
+            }
+            setCommandMenuIndex(0);
+            if (screen === "home")
+                setSelectedIdx(0);
+            return true;
+        }
+        if (key.backspace) {
+            if (key.ctrl) {
+                deleteWordBefore();
+            }
+            else if (cursorPos > 0) {
+                setInputText((c) => c.slice(0, cursorPos - 1) + c.slice(cursorPos));
+                setCursorPos((p) => Math.max(0, p - 1));
+            }
+            setCommandMenuIndex(0);
+            if (screen === "home")
+                setSelectedIdx(0);
+            return true;
+        }
+        if (key.ctrl && (char === "a" || char === "b")) {
+            setCursorPos(0);
+            return true;
+        }
+        if (key.ctrl && (char === "e" || char === "f")) {
+            setCursorPos(inputText.length);
+            return true;
+        }
+        if (key.ctrl && char === "w") {
+            deleteWordBefore();
+            setCommandMenuIndex(0);
+            if (screen === "home")
+                setSelectedIdx(0);
+            return true;
+        }
+        if (key.escape) {
+            setInputText("");
+            setCursorPos(0);
+            setCommandMenuIndex(0);
+            setHistoryIndex(-1);
+            if (screen === "home")
+                setSelectedIdx(0);
+            return true;
+        }
+        if (char && !key.ctrl && !key.meta) {
+            setInputText((c) => c.slice(0, cursorPos) + char + c.slice(cursorPos));
+            setCursorPos((p) => p + char.length);
+            setCommandMenuIndex(0);
+            setHeroHidden(true);
+            setHistoryIndex(-1);
+            if (screen === "home")
+                setSelectedIdx(0);
+            return true;
+        }
+        return false;
+    };
+    useInput((char, key) => {
+        if (char && (char.includes("[<") || /^\d+;\d+;\d+[Mm]$/u.test(char)))
+            return;
+        if (approvalPending) {
+            if (char === "y" || char === "Y" || key.return) {
+                const p = approvalPending;
+                setApprovalPending(null);
+                p.resolve(true);
+            }
+            else if (char === "n" || char === "N" || key.escape) {
+                const p = approvalPending;
+                setApprovalPending(null);
+                p.resolve(false);
+            }
+            return;
+        }
+        if (menu) {
+            if (key.escape) {
+                setMenu(null);
+                return;
+            }
+            if (menu.loading)
+                return;
+            const mFiltered = menu.query
+                ? menu.items.filter((item) => item.toLowerCase().includes(menu.query.toLowerCase()))
+                : menu.items;
+            if (key.upArrow) {
+                setMenu((m) => (m ? { ...m, index: Math.max(0, Math.min(m.index, mFiltered.length - 1) - 1) } : m));
+                return;
+            }
+            if (key.downArrow) {
+                setMenu((m) => (m ? { ...m, index: Math.max(0, Math.min(mFiltered.length - 1, m.index + 1)) } : m));
+                return;
+            }
+            if (key.return) {
+                const value = mFiltered[menu.index];
+                if (value) {
+                    setMenu(null);
+                    void applyMenuSelection({ ...menu, items: [value], index: 0 });
+                }
+                return;
+            }
+            if (key.backspace || key.delete) {
+                setMenu((m) => (m ? { ...m, query: m.query.slice(0, -1), index: 0 } : m));
+                return;
+            }
+            if (char.length === 1 && !key.ctrl && !key.meta) {
+                setMenu((m) => (m ? { ...m, query: m.query + char, index: 0 } : m));
+                return;
+            }
+            return;
+        }
+        if (helpOpen) {
+            if (key.escape || key.return || char === "q")
+                setHelpOpen(false);
+            return;
+        }
+        if (mcpOpen) {
+            if (key.escape || key.return || char === "q")
+                setMcpOpen(false);
+            return;
+        }
+        if (screen === "chat" && busy && key.escape) {
+            stopTurn();
+            return;
+        }
+        if (activeSuggestions.length > 0) {
+            if (key.upArrow) {
+                setCommandMenuIndex((i) => Math.max(0, i - 1));
+                return;
+            }
+            if (key.downArrow) {
+                setCommandMenuIndex((i) => Math.min(activeSuggestions.length - 1, i + 1));
+                return;
+            }
+            if (key.tab) {
+                acceptActiveSuggestion(activeSuggestions[Math.min(commandMenuIndex, activeSuggestions.length - 1)] ?? inputText);
+                return;
+            }
+        }
+        if (screen === "chat" && (key.pageUp || key.pageDown)) {
+            setScrollOffset((off) => {
+                const step = Math.max(1, Math.floor(contentRows / 2));
+                if (key.pageUp)
+                    return Math.min(off + step, maxScrollOffset);
+                return Math.max(0, off - step);
+            });
+            return;
+        }
+        // Cancel pendingRerun if user types something other than /rerun
+        if (pendingRerun && char && !(inputText + char).trim().startsWith("/rerun")) {
+            setPendingRerun(false);
+        }
+        if (screen === "chat" && inputHistory.length > 0) {
+            if (key.upArrow && !inputText) {
+                const idx = historyIndex === -1 ? inputHistory.length - 1 : Math.max(0, historyIndex - 1);
+                setHistoryIndex(idx);
+                setInputText(inputHistory[idx]);
+                setCursorPos(inputHistory[idx].length);
+                return;
+            }
+            if (key.downArrow && historyIndex >= 0) {
+                if (historyIndex === inputHistory.length - 1) {
+                    setHistoryIndex(-1);
+                    setInputText("");
+                    setCursorPos(0);
+                }
+                else {
+                    const idx = historyIndex + 1;
+                    setHistoryIndex(idx);
+                    setInputText(inputHistory[idx]);
+                    setCursorPos(inputHistory[idx].length);
+                }
+                return;
+            }
+        }
+        if (sessionsModalOpen) {
+            if (key.upArrow) {
+                deleteArmedRef.current = null;
+                setSessionsModalIdx((i) => Math.max(0, i - 1));
+            }
+            else if (key.downArrow) {
+                deleteArmedRef.current = null;
+                setSessionsModalIdx((i) => Math.min(sessions.length - 1, i + 1));
+            }
+            else if (char === "d") {
+                if (deleteArmedRef.current === sessionsModalIdx) {
+                    deleteArmedRef.current = null;
+                    deleteSession(sessionsModalIdx);
+                }
+                else {
+                    deleteArmedRef.current = sessionsModalIdx;
+                    setNotice("Press d again to delete this session permanently.");
+                }
+            }
+            else if (key.return) {
+                deleteArmedRef.current = null;
+                const s = sessions[sessionsModalIdx];
+                if (s) {
+                    setSessionsModalOpen(false);
+                    void openRun(s.path);
+                }
+            }
+            else if (key.escape) {
+                deleteArmedRef.current = null;
+                setSessionsModalOpen(false);
+            }
+            return;
+        }
+        if (screen === "home") {
+            const hasBrowse = sessions.length > 0;
+            const sessionItems = Math.min(sessions.length, 6);
+            const browseIdx = hasBrowse ? sessionItems : -1;
+            const newIdx = hasBrowse ? sessionItems + 1 : sessionItems;
+            const quitIdx = hasBrowse ? sessionItems + 2 : sessionItems + 1;
+            const maxHomeIdx = quitIdx;
+            if (key.upArrow && !activeSuggestions.length)
+                setSelectedIdx((i) => Math.max(0, i - 1));
+            else if (key.downArrow && !activeSuggestions.length)
+                setSelectedIdx((i) => Math.min(maxHomeIdx, i + 1));
+            else if (key.return) {
+                if (activeSuggestions.length > 0 && activeSuggestionKind === "command" && inputText.trim().startsWith("/")) {
+                    void submitHome(activeSuggestions[Math.min(commandMenuIndex, activeSuggestions.length - 1)] ?? inputText);
+                }
+                else if (activeSuggestions.length > 0 && activeSuggestionKind === "file") {
+                    acceptActiveSuggestion(activeSuggestions[Math.min(commandMenuIndex, activeSuggestions.length - 1)] ?? inputText);
+                }
+                else if (activeSuggestions.length > 0 && activeSuggestionKind === "session") {
+                    acceptActiveSuggestion(activeSuggestions[Math.min(commandMenuIndex, activeSuggestions.length - 1)] ?? inputText);
+                }
+                else if (inputText.trim()) {
+                    void submitHome(inputText);
+                }
+                else if (selectedIdx === browseIdx) {
+                    setSessionsModalOpen(true);
+                    setSessionsModalIdx(0);
+                }
+                else if (selectedIdx === newIdx) {
+                    setNotice("Type a question below to start a new research run.");
+                }
+                else if (selectedIdx === quitIdx) {
+                    exit();
+                }
+                else {
+                    void submitHome("");
+                }
+            }
+            else if (char === "q" && !inputText)
+                exit();
+            else if (key.ctrl && char === "d" && !inputText)
+                exit();
+            else
+                editInput(char, key);
+        }
+        else {
+            if (!inputText && !busy) {
+                if (char === "c") {
+                    hasFocusedGroup ? toggleFocusedGroup() : toggleAllGroups();
+                    return;
+                }
+                if (char === "[") {
+                    focusPrevGroup();
+                    return;
+                }
+                if (char === "]") {
+                    focusNextGroup();
+                    return;
+                }
+            }
+            if (key.escape && !inputText && hasFocusedGroup) {
+                unfocusGroup();
+                return;
+            }
+            if (key.return) {
+                if (activeSuggestions.length > 0 && activeSuggestionKind === "command" && inputText.trim().startsWith("/")) {
+                    submitChat(activeSuggestions[Math.min(commandMenuIndex, activeSuggestions.length - 1)] ?? inputText);
+                }
+                else if (activeSuggestions.length > 0 && activeSuggestionKind === "file") {
+                    acceptActiveSuggestion(activeSuggestions[Math.min(commandMenuIndex, activeSuggestions.length - 1)] ?? inputText);
+                }
+                else if (activeSuggestions.length > 0 && activeSuggestionKind === "session") {
+                    acceptActiveSuggestion(activeSuggestions[Math.min(commandMenuIndex, activeSuggestions.length - 1)] ?? inputText);
+                }
+                else {
+                    submitChat(inputText);
+                }
+            }
+            else
+                editInput(char, key);
+        }
+    }, { isActive: true });
+}

package/dist/ui/ink/hooks/use-mouse.js

@@ -0,0 +1,31 @@
+import { useCallback, useRef, useState } from "react";
+export function useMouse(onWheel) {
+    const clickMapRef = useRef(new Map());
+    const hoverMapRef = useRef(new Map());
+    const [hoveredIdx, setHoveredIdx] = useState(null);
+    const onWheelRef = useRef(onWheel);
+    onWheelRef.current = onWheel;
+    const handleMouseData = useCallback((data) => {
+        const s = data.toString("utf8");
+        const m = /\x1b\[<(\d+);(\d+);(\d+)([Mm])/u.exec(s);
+        if (!m)
+            return;
+        const code = Number(m[1]);
+        const y = Number(m[3]);
+        if ((code & 64) !== 0) { // wheel event: 64 = up, 65 = down (modifier bits 4/8/16 may be set)
+            onWheelRef.current?.((code & 1) === 0 ? 1 : -1);
+            return;
+        }
+        if ((code & 32) !== 0) { // motion event → hover
+            const idx = hoverMapRef.current.get(y);
+            setHoveredIdx(idx ?? null);
+            return;
+        }
+        if (m[4] !== "M" || (code & 3) !== 0)
+            return; // left button press only
+        const action = clickMapRef.current.get(y);
+        if (action)
+            action();
+    }, []);
+    return { clickMapRef, hoverMapRef, hoveredIdx, setHoveredIdx, handleMouseData };
+}

package/dist/ui/ink/hooks/use-session.js

@@ -0,0 +1,103 @@
+import { useCallback } from "react";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { listRuns, summarizeRun } from "../../../storage/run-store.js";
+import { getSession, attachSubscriber } from "../session-manager.js";
+export function useSession(o) {
+    const { config, currentRunPath, conversationRef, feedRef, turnsRef, startedRef, runTurnRef, setSessions, setRunState, setCurrentRunPath, setInputText, setCursorPos, setFeed, setUsage, setScrollOffset, setScreen, setMode, setBusy, setApprovalPending, getSubscriber, } = o;
+    const refreshSessions = useCallback(async () => {
+        const runs = await listRuns(config);
+        setSessions(runs);
+    }, [config]);
+    const refreshRun = useCallback(async () => {
+        if (currentRunPath)
+            setRunState(await summarizeRun(currentRunPath));
+    }, [currentRunPath]);
+    const openRun = useCallback(async (runPath, initialQuestion) => {
+        setCurrentRunPath(runPath);
+        setInputText("");
+        setCursorPos(0);
+        // If a background session is already running for this path, reattach to it.
+        const live = getSession(runPath);
+        if (live) {
+            startedRef.current = runPath;
+            setScrollOffset(0);
+            setScreen("chat");
+            setMode(live.feedBuffer.some((it) => it.kind === "tool" || it.kind === "status"));
+            const buffered = attachSubscriber(runPath, getSubscriber());
+            if (buffered.length > 0) {
+                setFeed(buffered);
+                feedRef.current = buffered;
+            }
+            setBusy(live.busy);
+            if (live.approvalPending)
+                setApprovalPending(live.approvalPending);
+            const resumedState = await summarizeRun(runPath).catch(() => null);
+            setRunState(resumedState);
+            return;
+        }
+        try {
+            const raw = await readFile(join(runPath, "convo.json"), "utf8");
+            const saved = JSON.parse(raw);
+            if (saved.feed && saved.feed.length > 0) {
+                const filteredFeed = saved.feed.filter((item) => !(item.kind === "status" && item.text === "This will wipe the conversation history. Press /rerun again to confirm."));
+                const restoredFeed = [...filteredFeed, { kind: "status", text: "— resumed —" }];
+                setFeed(restoredFeed);
+                feedRef.current = restoredFeed;
+                conversationRef.current = saved.messages ?? [];
+                turnsRef.current = saved.usage?.turns ?? [];
+                setUsage(saved.usage?.byModel ?? {});
+                startedRef.current = runPath;
+                setScrollOffset(0);
+                setScreen("chat");
+                const resumedState = await summarizeRun(runPath).catch(() => null);
+                setRunState(resumedState);
+                setMode((resumedState?.claimCount ?? 0) > 0 || (resumedState?.sourceCount ?? 0) > 0);
+                return;
+            }
+        }
+        catch (e) {
+            if (e.code !== "ENOENT") {
+                conversationRef.current = [];
+                const errMsg = e instanceof Error ? e.message : String(e);
+                const errFeed = [{ kind: "status", text: `Could not restore session: ${errMsg}` }];
+                setFeed(errFeed);
+                feedRef.current = errFeed;
+                startedRef.current = runPath;
+                setScrollOffset(0);
+                setScreen("chat");
+                return;
+            }
+        }
+        conversationRef.current = [];
+        turnsRef.current = [];
+        setUsage({});
+        startedRef.current = runPath;
+        setMode(false);
+        const shortModel = config.model.includes("/") ? (config.model.split("/").pop() ?? config.model) : config.model;
+        const startStatus = [
+            shortModel,
+            `${config.search.provider} ×${config.search.maxResults}`,
+            `${config.approvalMode} approvals`,
+            ...(() => {
+                const mcpCount = (config.mcp.chromeDevtools.enabled ? 1 : 0) + config.mcp.servers.filter((s) => s.enabled).length;
+                return mcpCount > 0 ? [`${mcpCount} mcp`] : [];
+            })(),
+        ].join("  ·  ");
+        const freshFeed = initialQuestion
+            ? [{ kind: "user", text: initialQuestion, ts: Date.now() }, { kind: "status", text: startStatus }]
+            : [{ kind: "status", text: startStatus }];
+        setFeed(freshFeed);
+        feedRef.current = freshFeed;
+        setScrollOffset(0);
+        setScreen("chat");
+        void (async () => {
+            await summarizeRun(runPath).then(setRunState).catch(() => { });
+            // Attach subscriber BEFORE starting the turn so no items are emitted without a listener.
+            attachSubscriber(runPath, getSubscriber());
+            await runTurnRef.current("Answer my question concisely using web search. If it genuinely needs deep, multi-source, verifiable research, call requestFullResearch to ask me to approve the full research harness.");
+        })();
+    }, [config, setCurrentRunPath, setInputText, setCursorPos, setFeed, setUsage, setScrollOffset,
+        setScreen, setRunState, setMode, setBusy, setApprovalPending, getSubscriber]);
+    return { refreshSessions, refreshRun, openRun };
+}

package/dist/ui/ink/hooks/use-settings.js

@@ -0,0 +1,155 @@
+import { useCallback, useRef, useState } from "react";
+import { saveGlobalConfig } from "../../../config/load-config.js";
+import { setEnvKey, isManagedEnvKey, MANAGED_ENV_KEYS } from "../../../config/env-store.js";
+import { detectEnv } from "../../../providers/llm/readiness.js";
+import { listModels } from "../../../providers/llm/models.js";
+import { LLM_PROVIDERS, LLM_PROVIDER_LABELS, defaultModelFor } from "../../../providers/llm/registry.js";
+import { PROVIDERS } from "../constants.js";
+import { prettifyModelId } from "../lib/utils.js";
+import { useMountEffect } from "../components/effects.js";
+export function useSettings({ config, setConfig, screen, pushFeed, setNotice }) {
+    const [menu, setMenu] = useState(null);
+    const modelsRef = useRef(new Map());
+    const [modelName, setModelName] = useState(() => prettifyModelId(config.model));
+    const currentModelIdRef = useRef(config.model);
+    const resolveModelName = useCallback((id) => {
+        currentModelIdRef.current = id;
+        const cached = modelsRef.current.get(id);
+        if (cached) {
+            setModelName(cached);
+            return;
+        }
+        setModelName(prettifyModelId(id));
+        void listModels(config).then((models) => {
+            const map = new Map();
+            for (const m of models)
+                map.set(m.id, m.name && m.name.trim() ? m.name : prettifyModelId(m.id));
+            modelsRef.current = map;
+            if (currentModelIdRef.current === id)
+                setModelName(map.get(id) ?? prettifyModelId(id));
+        }).catch(() => { });
+    }, [config]);
+    useMountEffect(() => { resolveModelName(config.model); });
+    const applyModel = useCallback(async (id) => {
+        const next = { ...config, model: id, lastModels: { ...config.lastModels, [config.llmProvider]: id } };
+        setConfig(next);
+        resolveModelName(id);
+        await saveGlobalConfig(next);
+        return `Model set to ${id}.`;
+    }, [config, resolveModelName, setConfig]);
+    const applyProvider = useCallback(async (provider) => {
+        const next = { ...config, search: { ...config.search, provider } };
+        setConfig(next);
+        await saveGlobalConfig(next);
+        return `Search provider set to ${provider}.`;
+    }, [config, setConfig]);
+    const applyLlmProvider = useCallback(async (provider) => {
+        if (provider === config.llmProvider)
+            return `LLM provider already set to ${LLM_PROVIDER_LABELS[provider]}.`;
+        const model = config.lastModels[provider] ?? defaultModelFor(provider);
+        const next = {
+            ...config,
+            llmProvider: provider,
+            model,
+            lastModels: { ...config.lastModels, [config.llmProvider]: config.model }
+        };
+        setConfig(next);
+        modelsRef.current = new Map();
+        await saveGlobalConfig(next);
+        return `LLM provider set to ${LLM_PROVIDER_LABELS[provider]} (model: ${model}).`;
+    }, [config, setConfig]);
+    const openMenu = useCallback(async (type) => {
+        if (type === "provider") {
+            const idx = Math.max(0, PROVIDERS.indexOf(config.search.provider));
+            setMenu({ type, items: PROVIDERS, index: idx, query: "" });
+            return;
+        }
+        if (type === "llm") {
+            const idx = Math.max(0, LLM_PROVIDERS.indexOf(config.llmProvider));
+            setMenu({ type, items: LLM_PROVIDERS, index: idx, query: "" });
+            return;
+        }
+        setMenu({ type: "model", items: [], index: 0, loading: true, query: "" });
+        try {
+            const models = await listModels(config);
+            const ids = models.map((m) => m.id);
+            const idx = Math.max(0, ids.indexOf(config.model));
+            setMenu({ type: "model", items: ids, index: idx, query: "" });
+        }
+        catch (error) {
+            setMenu(null);
+            const msg = error instanceof Error ? error.message : String(error);
+            if (screen === "chat")
+                pushFeed({ kind: "status", text: msg });
+            else
+                setNotice(msg);
+        }
+    }, [config, pushFeed, screen, setNotice]);
+    const applyMenuSelection = useCallback(async (selected) => {
+        const value = selected.items[selected.index];
+        if (!value)
+            return;
+        const result = selected.type === "model"
+            ? await applyModel(value)
+            : selected.type === "llm"
+                ? await applyLlmProvider(value)
+                : await applyProvider(value);
+        if (selected.type === "llm")
+            resolveModelName(config.lastModels[value] ?? defaultModelFor(value));
+        if (screen === "chat")
+            pushFeed({ kind: "status", text: result });
+        else
+            setNotice(result);
+    }, [applyModel, applyProvider, applyLlmProvider, resolveModelName, pushFeed, screen, setNotice, config.lastModels]);
+    const handleSettings = useCallback(async (text) => {
+        const parts = text.split(/\s+/u);
+        const cmd = parts[0];
+        const rest = parts.slice(1);
+        const arg = rest.join(" ").trim();
+        if (cmd === "/model") {
+            if (!arg)
+                return `Current model: ${config.model}`;
+            const next = { ...config, model: arg, lastModels: { ...config.lastModels, [config.llmProvider]: arg } };
+            setConfig(next);
+            resolveModelName(arg);
+            await saveGlobalConfig(next);
+            return `Model set to ${arg}.`;
+        }
+        if (cmd === "/llm") {
+            if (!arg)
+                return `Current LLM provider: ${LLM_PROVIDER_LABELS[config.llmProvider]} (${config.llmProvider})\nOptions: ${LLM_PROVIDERS.join(", ")}`;
+            if (!LLM_PROVIDERS.includes(arg))
+                return `Unknown LLM provider "${arg}". Options: ${LLM_PROVIDERS.join(", ")}`;
+            const result = await applyLlmProvider(arg);
+            resolveModelName(config.lastModels[arg] ?? defaultModelFor(arg));
+            return result;
+        }
+        if (cmd === "/provider") {
+            if (!arg)
+                return `Current search provider: ${config.search.provider}\nOptions: ${PROVIDERS.join(", ")}`;
+            if (!PROVIDERS.includes(arg))
+                return `Unknown provider "${arg}". Options: ${PROVIDERS.join(", ")}`;
+            const next = { ...config, search: { ...config.search, provider: arg } };
+            setConfig(next);
+            await saveGlobalConfig(next);
+            return `Search provider set to ${arg}.`;
+        }
+        if (cmd === "/key") {
+            const name = (rest[0] ?? "").toUpperCase();
+            const value = rest.slice(1).join(" ").trim();
+            if (!name || !value)
+                return `Usage: /key <NAME> <value>\nManaged keys: ${MANAGED_ENV_KEYS.join(", ")}`;
+            if (!isManagedEnvKey(name))
+                return `Unknown key "${name}". Managed keys: ${MANAGED_ENV_KEYS.join(", ")}`;
+            await setEnvKey(name, value);
+            return `${name} saved to ~/.scira/.env and active for this session.`;
+        }
+        if (cmd === "/keys") {
+            return detectEnv(config.search.provider, config.llmProvider)
+                .map((c) => `${c.present ? "set    " : "missing"} ${c.name}${c.required ? " (required)" : ""}`)
+                .join("\n");
+        }
+        return null;
+    }, [config, resolveModelName, setConfig, applyLlmProvider]);
+    return { menu, setMenu, modelName, resolveModelName, openMenu, applyMenuSelection, handleSettings };
+}