@getmegabrain/cli 0.1.5 → 0.1.7

package/dist/science/server.js

@@ -0,0 +1,353 @@
+import { randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+import { readCredentials, writeCredentials, clearCredentials } from '../credentials.js';
+import { startDeviceAuth } from '../device-auth.js';
+import { NonceStore } from './nonce.js';
+import { homePage, loginPage, nonceInvalidPage, nonceLandingPage, projectPage, sessionPage, startWizardPage, } from './pages.js';
+import { FEATURED_CONNECTORS, NETWORK_CATEGORIES, WorkspaceStore } from './store.js';
+import { KernelManager } from './kernel.js';
+import { AgentSession, pythonTool } from './agent/agent.js';
+import { GatewayModel } from './agent/model.js';
+/**
+ * The `megabrain science` local daemon's HTTP server. Serves the sign-in hand-off on
+ * localhost (docs/megabrain-science/reference/claude-science-flow.md §1.1) and, once signed
+ * in, a placeholder app shell where the reused session UI will mount. Two trust layers:
+ *   1. a single-use nonce authorizes a browser to drive this daemon (a printed localhost URL),
+ *   2. MegaBrain device-auth authenticates the account (reused from the CLI).
+ */
+const COOKIE = 'mb_sci';
+const PREFERRED_PORT = 8765;
+const SESSION_CLIENT = fileURLToPath(new URL('./session-client.js', import.meta.url));
+export async function startScienceServer(host = '127.0.0.1') {
+    const nonces = new NonceStore();
+    const trusted = new Set();
+    const store = new WorkspaceStore();
+    const kernels = new KernelManager();
+    let pending = null;
+    // Per-session Server-Sent-Events fan-out. Kernel frames + agent transcript events both
+    // flow to every browser watching a session, tagged with a `channel`.
+    const sseClients = new Map();
+    const kernelHooked = new Set();
+    const fanout = (sid, channel, payload) => {
+        const set = sseClients.get(sid);
+        if (!set)
+            return;
+        const line = `data: ${JSON.stringify({ channel, payload })}\n\n`;
+        for (const r of set)
+            r.write(line);
+    };
+    const isSignedIn = () => readCredentials() !== null;
+    const readBody = (req) => new Promise(resolve => {
+        let raw = '';
+        req.on('data', chunk => {
+            raw += chunk;
+            if (raw.length > 1_000_000)
+                req.destroy(); // guard against oversized bodies
+        });
+        req.on('end', () => {
+            try {
+                resolve(raw ? JSON.parse(raw) : {});
+            }
+            catch {
+                resolve({});
+            }
+        });
+        req.on('error', () => resolve({}));
+    });
+    const str = (v) => (typeof v === 'string' ? v : undefined);
+    const cookieId = (req) => {
+        const raw = req.headers.cookie ?? '';
+        for (const part of raw.split(';')) {
+            const [k, v] = part.trim().split('=');
+            if (k === COOKIE && v)
+                return v;
+        }
+        return null;
+    };
+    const isTrusted = (req) => {
+        const id = cookieId(req);
+        return id !== null && trusted.has(id);
+    };
+    const html = (res, body, status = 200) => {
+        res.writeHead(status, { 'content-type': 'text/html; charset=utf-8' });
+        res.end(body);
+    };
+    const json = (res, body, status = 200) => {
+        res.writeHead(status, { 'content-type': 'application/json' });
+        res.end(JSON.stringify(body));
+    };
+    const redirect = (res, location) => {
+        res.writeHead(302, { location });
+        res.end();
+    };
+    const server = createServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? host}`);
+        const path = url.pathname;
+        const method = req.method ?? 'GET';
+        const seg = path.split('/').filter(Boolean);
+        // Static workspace client (referenced by the session page).
+        if (path === '/session-client.js' && method === 'GET') {
+            res.writeHead(200, {
+                'content-type': 'text/javascript; charset=utf-8',
+                'cache-control': 'no-cache',
+            });
+            res.end(readFileSync(SESSION_CLIENT, 'utf8'));
+            return;
+        }
+        // ── Sign-in hand-off ───────────────────────────────────────────────
+        if (path === '/' && url.searchParams.has('nonce')) {
+            const result = nonces.claim(url.searchParams.get('nonce') ?? '');
+            if (result !== 'ok')
+                return html(res, nonceInvalidPage(), 410);
+            const id = randomBytes(18).toString('hex');
+            trusted.add(id);
+            res.setHeader('set-cookie', `${COOKIE}=${id}; HttpOnly; SameSite=Lax; Path=/`);
+            return html(res, nonceLandingPage(url.searchParams.get('nonce') ?? ''));
+        }
+        if (path === '/') {
+            if (!isTrusted(req))
+                return html(res, nonceInvalidPage(), 401);
+            const creds = readCredentials();
+            if (!creds)
+                return redirect(res, '/login');
+            // First run: send new accounts through the onboarding wizard before Home.
+            if (!store.getSettings().onboarded)
+                return redirect(res, '/start');
+            return html(res, homePage(creds.userEmail));
+        }
+        if (path === '/login' && method === 'GET') {
+            if (!isTrusted(req))
+                return html(res, nonceInvalidPage(), 401);
+            return isSignedIn() ? redirect(res, '/') : html(res, loginPage());
+        }
+        if (path === '/start' && method === 'GET') {
+            if (!isTrusted(req))
+                return html(res, nonceInvalidPage(), 401);
+            if (!isSignedIn())
+                return redirect(res, '/login');
+            const s = store.getSettings();
+            return html(res, startWizardPage({
+                networkCategories: [...NETWORK_CATEGORIES],
+                connectorCatalog: [...FEATURED_CONNECTORS],
+                network: s.network,
+                connectors: s.connectors,
+                profile: s.profile,
+            }));
+        }
+        // ── Workbench pages (trusted + signed in) ───────────────────────────
+        if (seg[0] === 'projects' && method === 'GET') {
+            if (!isTrusted(req))
+                return html(res, nonceInvalidPage(), 401);
+            if (!isSignedIn())
+                return redirect(res, '/login');
+            if (seg.length === 2)
+                return html(res, projectPage(seg[1] ?? ''));
+            if (seg.length === 4 && seg[2] === 'frames') {
+                return html(res, sessionPage(seg[1] ?? '', seg[3] ?? ''));
+            }
+        }
+        // ── Auth API (browser-driven, gated on the local-trust cookie) ──────
+        if (path === '/api/signin' && method === 'POST') {
+            if (!isTrusted(req))
+                return json(res, { error: 'untrusted' }, 401);
+            if (isSignedIn())
+                return json(res, { signedIn: true });
+            const respond = (p) => json(res, { verificationUrl: p.verificationUrl, code: p.code });
+            if (pending)
+                return respond(pending);
+            void startDeviceAuth()
+                .then(p => {
+                pending = p;
+                p.completed
+                    .then(creds => writeCredentials(creds))
+                    .catch(() => {
+                    /* denied / expired — the browser can retry, which mints a new code */
+                })
+                    .finally(() => {
+                    pending = null;
+                });
+                respond(p);
+            })
+                .catch(() => json(res, { error: 'start-failed' }, 502));
+            return;
+        }
+        if (path === '/api/auth/status' && method === 'GET') {
+            const creds = readCredentials();
+            return json(res, { signedIn: creds !== null, userEmail: creds?.userEmail ?? null });
+        }
+        if (path === '/api/signout' && method === 'POST') {
+            clearCredentials();
+            return json(res, { ok: true });
+        }
+        // ── Onboarding API (#286). Signed-in only. ──────────────────────────
+        if (path === '/api/onboarding') {
+            if (!isSignedIn())
+                return json(res, { error: 'signed-out' }, 401);
+            if (method === 'GET')
+                return json(res, store.getSettings());
+            if (method === 'PUT') {
+                const b = await readBody(req);
+                const arr = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string') : undefined;
+                return json(res, store.updateSettings({
+                    network: arr(b.network),
+                    connectors: arr(b.connectors),
+                    skills: arr(b.skills),
+                    profile: str(b.profile),
+                    onboarded: typeof b.onboarded === 'boolean' ? b.onboarded : undefined,
+                }));
+            }
+        }
+        if (path === '/api/onboarding/start' && method === 'POST') {
+            if (!isSignedIn())
+                return json(res, { error: 'signed-out' }, 401);
+            const b = await readBody(req);
+            const task = str(b.task)?.trim() ?? '';
+            const profile = str(b.profile)?.trim() ?? '';
+            store.updateSettings({ onboarded: true, ...(profile ? { profile } : {}) });
+            const project = store.createProject({
+                name: profile ? profile.slice(0, 60) : 'My research',
+                agentContext: profile,
+            });
+            const session = store.createSession({
+                projectId: project.id,
+                title: task || 'New session',
+                summary: task,
+            });
+            return json(res, { projectId: project.id, sessionId: session?.id ?? null }, 201);
+        }
+        // ── Session event stream + agent (#274/#276/#277). Signed-in only. ──
+        // One SSE per session carries two channels: `kernel` (raw kernel status/output frames)
+        // and `agent` (the agent loop's transcript events). The agent's model runs in the cloud
+        // (Gateway) but drives the local kernel — compute stays on the machine.
+        if (seg[0] === 'api' &&
+            seg[1] === 'sessions' &&
+            seg[2] &&
+            (seg[3] === 'events' || seg[3] === 'agent' || seg[3] === 'kernel')) {
+            const creds = readCredentials();
+            if (!creds)
+                return json(res, { error: 'signed-out' }, 401);
+            const sid = seg[2];
+            if (seg[3] === 'events' && method === 'GET') {
+                res.writeHead(200, {
+                    'content-type': 'text/event-stream',
+                    'cache-control': 'no-cache',
+                    connection: 'keep-alive',
+                });
+                let set = sseClients.get(sid);
+                if (!set) {
+                    set = new Set();
+                    sseClients.set(sid, set);
+                }
+                set.add(res);
+                if (!kernelHooked.has(sid)) {
+                    kernelHooked.add(sid);
+                    kernels.get(sid).onFrame(frame => fanout(sid, 'kernel', frame));
+                }
+                req.on('close', () => sseClients.get(sid)?.delete(res));
+                return;
+            }
+            if (seg[3] === 'kernel' && seg[4] === 'restart' && method === 'POST') {
+                kernels.restart(sid);
+                return json(res, { ok: true });
+            }
+            if (seg[3] === 'agent' && method === 'POST') {
+                const b = await readBody(req);
+                const prompt = str(b.prompt)?.trim() ?? '';
+                if (!prompt)
+                    return json(res, { error: 'prompt-required' }, 400);
+                const session = store.getSession(sid);
+                const project = session ? store.getProject(session.projectId) : null;
+                store.touchSession(sid, session && !session.summary ? { summary: prompt } : undefined);
+                fanout(sid, 'agent', { type: 'user', text: prompt });
+                const agent = new AgentSession(new GatewayModel({ apiKey: creds.token }), [pythonTool(kernels.get(sid))], evt => fanout(sid, 'agent', evt), project?.agentContext ?? '');
+                void agent.run(prompt);
+                return json(res, { ok: true });
+            }
+        }
+        // ── Workspace API (projects/sessions, #270/#271). Signed-in only. ────
+        if (path.startsWith('/api/projects') || path.startsWith('/api/sessions')) {
+            if (!isSignedIn())
+                return json(res, { error: 'signed-out' }, 401);
+            if (path === '/api/projects' && method === 'GET')
+                return json(res, store.listProjects());
+            if (path === '/api/projects' && method === 'POST') {
+                const b = await readBody(req);
+                const name = str(b.name);
+                if (!name)
+                    return json(res, { error: 'name-required' }, 400);
+                return json(res, store.createProject({
+                    name,
+                    description: str(b.description),
+                    agentContext: str(b.agentContext),
+                }), 201);
+            }
+            if (seg[0] === 'api' && seg[1] === 'projects' && seg[2]) {
+                const pid = seg[2];
+                if (seg.length === 3 && method === 'GET') {
+                    const project = store.getProject(pid);
+                    return project
+                        ? json(res, { project, sessions: store.listSessions(pid) })
+                        : json(res, { error: 'not-found' }, 404);
+                }
+                if (seg.length === 3 && method === 'PATCH') {
+                    const b = await readBody(req);
+                    const updated = store.updateProject(pid, {
+                        name: str(b.name),
+                        description: str(b.description),
+                        agentContext: str(b.agentContext),
+                    });
+                    return updated ? json(res, updated) : json(res, { error: 'not-found' }, 404);
+                }
+                if (seg.length === 4 && seg[3] === 'sessions' && method === 'POST') {
+                    const b = await readBody(req);
+                    const session = store.createSession({
+                        projectId: pid,
+                        title: str(b.title),
+                        summary: str(b.summary),
+                    });
+                    return session ? json(res, session, 201) : json(res, { error: 'not-found' }, 404);
+                }
+            }
+            if (path === '/api/sessions/recent' && method === 'GET') {
+                return json(res, store.recentSessions());
+            }
+            if (seg[0] === 'api' && seg[1] === 'sessions' && seg[2] && method === 'GET') {
+                const session = store.getSession(seg[2]);
+                return session ? json(res, session) : json(res, { error: 'not-found' }, 404);
+            }
+            return json(res, { error: 'not-found' }, 404);
+        }
+        // Mint a fresh sign-in URL for `megabrain science url` (localhost-only, like the daemon
+        // itself — any local terminal can ask for a link; the account auth still gates access).
+        if (path === '/internal/mint' && method === 'POST') {
+            const origin = `http://${host}:${port}`;
+            return json(res, { url: `${origin}/?nonce=${nonces.create()}` });
+        }
+        res.writeHead(404, { 'content-type': 'text/plain' });
+        res.end('Not found');
+    });
+    const port = await listen(server, host, PREFERRED_PORT);
+    const origin = () => `http://${host}:${port}`;
+    return { server, port, nonces, kernels, origin };
+}
+/** Bind the preferred port, falling back to an OS-assigned one if it's taken. */
+function listen(server, host, preferred) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            if (err.code === 'EADDRINUSE') {
+                server.listen(0, host);
+                return;
+            }
+            reject(err);
+        };
+        server.on('error', onError);
+        server.on('listening', () => {
+            server.off('error', onError);
+            const address = server.address();
+            resolve(typeof address === 'object' && address ? address.port : preferred);
+        });
+        server.listen(preferred, host);
+    });
+}

package/dist/science/session-client.js

@@ -0,0 +1,165 @@
+// Workspace client for a MegaBrain Science session (#271/#276/#277). Renders the sidebar
+// (sessions), the transcript (agent steps), and the composer; streams agent + kernel events
+// over SSE. Shipped as a static asset (see copy-assets) so it needs no build-time escaping.
+(function () {
+  var MB = window.__MB__ || {};
+  var sid = MB.sid,
+    pid = MB.pid;
+
+  var $ = function (id) {
+    return document.getElementById(id);
+  };
+  var transcript = $('transcript');
+  var scroller = document.querySelector('.transcript');
+  var composer = $('composer');
+  var sendBtn = $('send');
+  var kstate = $('kstate');
+  var lastCard = null;
+
+  function el(tag, cls, text) {
+    var e = document.createElement(tag);
+    if (cls) e.className = cls;
+    if (text != null) e.textContent = text;
+    return e;
+  }
+
+  function scroll() {
+    scroller.scrollTop = scroller.scrollHeight;
+  }
+
+  function addUser(text) {
+    var row = el('div', 'msg user');
+    row.appendChild(el('div', 'bubble', text));
+    transcript.appendChild(row);
+    scroll();
+  }
+  function addAgentText(text) {
+    var row = el('div', 'msg agent');
+    row.appendChild(el('div', 'prose', text));
+    transcript.appendChild(row);
+    scroll();
+  }
+  function addToolCall(tool, code) {
+    var card = el('div', 'step');
+    var head = el('div', 'step-head');
+    head.appendChild(el('span', 'step-dot'));
+    head.appendChild(el('span', 'step-title', tool === 'run_python' ? 'Ran Python' : tool));
+    card.appendChild(head);
+    var pre = el('pre', 'code');
+    pre.textContent = code;
+    card.appendChild(pre);
+    var out = el('pre', 'out');
+    out.hidden = true;
+    card.appendChild(out);
+    transcript.appendChild(card);
+    lastCard = card;
+    scroll();
+  }
+  function addToolResult(stdout, stderr) {
+    if (!lastCard) return;
+    var out = lastCard.querySelector('.out');
+    var text = (stdout || '') + (stderr ? (stdout ? '\n' : '') + stderr : '');
+    out.textContent = text || '(no output)';
+    out.hidden = false;
+    if (stderr) out.classList.add('err');
+    scroll();
+  }
+
+  function setRunning(on) {
+    sendBtn.disabled = on;
+    sendBtn.textContent = on ? 'Running…' : 'Send';
+  }
+
+  // ── Sidebar: this project's sessions ────────────────────────────────
+  function loadSidebar() {
+    if (!pid) return;
+    fetch('/api/projects/' + pid)
+      .then(function (r) {
+        return r.json();
+      })
+      .then(function (p) {
+        if (p.project) $('project-name').textContent = p.project.name;
+        var list = $('session-list');
+        list.textContent = '';
+        (p.sessions || []).forEach(function (s) {
+          var a = el('a', 'session' + (s.id === sid ? ' active' : ''), s.title);
+          a.href = '/projects/' + pid + '/frames/' + s.id;
+          list.appendChild(a);
+        });
+      });
+  }
+
+  // ── Live event stream ───────────────────────────────────────────────
+  function connect() {
+    var es = new EventSource('/api/sessions/' + sid + '/events');
+    es.onmessage = function (e) {
+      var m = JSON.parse(e.data);
+      if (m.channel === 'kernel') {
+        var f = m.payload;
+        if (f.type === 'status') kstate.textContent = f.state === 'busy' ? 'running' : f.state;
+        return;
+      }
+      var p = m.payload;
+      if (p.type === 'user') addUser(p.text);
+      else if (p.type === 'agent-text') addAgentText(p.text);
+      else if (p.type === 'tool-call') addToolCall(p.tool, p.code);
+      else if (p.type === 'tool-result') addToolResult(p.stdout, p.stderr);
+      else if (p.type === 'agent-done') setRunning(false);
+      else if (p.type === 'agent-error') {
+        addAgentText('⚠ ' + p.error);
+        setRunning(false);
+      }
+    };
+    es.onerror = function () {
+      kstate.textContent = 'reconnecting…';
+    };
+  }
+
+  function send() {
+    var text = composer.value.trim();
+    if (!text || sendBtn.disabled) return;
+    composer.value = '';
+    setRunning(true);
+    fetch('/api/sessions/' + sid + '/agent', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ prompt: text }),
+    }).catch(function () {
+      setRunning(false);
+    });
+  }
+
+  sendBtn.addEventListener('click', send);
+  composer.addEventListener('keydown', function (e) {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      send();
+    }
+  });
+  $('new-session').addEventListener('click', function () {
+    fetch('/api/projects/' + pid + '/sessions', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ title: 'New session' }),
+    })
+      .then(function (r) {
+        return r.json();
+      })
+      .then(function (s) {
+        location.href = '/projects/' + pid + '/frames/' + s.id;
+      });
+  });
+
+  fetch('/api/sessions/' + sid)
+    .then(function (r) {
+      return r.json();
+    })
+    .then(function (s) {
+      if (s && s.title) $('session-title').textContent = s.title;
+      // Prefill the composer with the seeded first task so the user can just hit Send.
+      if (s && (s.summary || s.title) && !composer.value) composer.value = s.summary || s.title;
+    });
+
+  loadSidebar();
+  connect();
+})();

package/dist/science/store.js

@@ -0,0 +1,160 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { MEGABRAIN_CONFIG_DIR } from '../paths.js';
+/** Scientific-web egress categories offered in onboarding step "Connect to the scientific web". */
+export const NETWORK_CATEGORIES = [
+    'NCBI / NIH',
+    'Genomics & biology',
+    'Proteomics',
+    'Literature & citations',
+    'Clinical & pharma',
+];
+/** Featured research connectors offered in onboarding step "Connectors & skills". */
+export const FEATURED_CONNECTORS = [
+    'BioMart',
+    'bioRxiv',
+    'Cancer Models',
+    'CellGuide',
+    'PubMed',
+    'OpenAlex',
+];
+function defaultSettings() {
+    return {
+        onboarded: false,
+        network: [...NETWORK_CATEGORIES],
+        connectors: [...FEATURED_CONNECTORS],
+        skills: [],
+        profile: '',
+    };
+}
+const STORE_FILE = path.join(MEGABRAIN_CONFIG_DIR, 'science-workspace.json');
+function id(prefix) {
+    return `${prefix}_${randomBytes(8).toString('hex')}`;
+}
+export class WorkspaceStore {
+    file;
+    now;
+    data;
+    constructor(file = STORE_FILE, now = () => new Date().toISOString()) {
+        this.file = file;
+        this.now = now;
+        this.data = this.load();
+    }
+    load() {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.file, 'utf8'));
+            return {
+                projects: parsed.projects ?? [],
+                sessions: parsed.sessions ?? [],
+                settings: parsed.settings,
+            };
+        }
+        catch {
+            return { projects: [], sessions: [] };
+        }
+    }
+    save() {
+        fs.mkdirSync(path.dirname(this.file), { recursive: true });
+        // Atomic write so a crash mid-save can't corrupt the workspace.
+        const tmp = `${this.file}.${randomBytes(4).toString('hex')}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(this.data, null, 2), { mode: 0o600 });
+        fs.renameSync(tmp, this.file);
+    }
+    // ── Projects ─────────────────────────────────────────────────────────
+    listProjects() {
+        return this.data.projects
+            .map(p => {
+            const sessions = this.data.sessions.filter(s => s.projectId === p.id);
+            const lastActivity = sessions.reduce((max, s) => (s.updatedAt > max ? s.updatedAt : max), p.updatedAt);
+            return { ...p, sessionCount: sessions.length, lastActivity };
+        })
+            .sort((a, b) => b.lastActivity.localeCompare(a.lastActivity));
+    }
+    getProject(projectId) {
+        return this.data.projects.find(p => p.id === projectId) ?? null;
+    }
+    createProject(input) {
+        const ts = this.now();
+        const project = {
+            id: id('proj'),
+            name: input.name.trim() || 'Untitled project',
+            description: input.description?.trim() ?? '',
+            agentContext: input.agentContext?.trim() ?? '',
+            createdAt: ts,
+            updatedAt: ts,
+        };
+        this.data.projects.push(project);
+        this.save();
+        return project;
+    }
+    updateProject(projectId, patch) {
+        const project = this.data.projects.find(p => p.id === projectId);
+        if (!project)
+            return null;
+        if (patch.name !== undefined)
+            project.name = patch.name.trim() || project.name;
+        if (patch.description !== undefined)
+            project.description = patch.description.trim();
+        if (patch.agentContext !== undefined)
+            project.agentContext = patch.agentContext.trim();
+        project.updatedAt = this.now();
+        this.save();
+        return project;
+    }
+    // ── Sessions ─────────────────────────────────────────────────────────
+    listSessions(projectId) {
+        return this.data.sessions
+            .filter(s => s.projectId === projectId)
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+    recentSessions(limit = 10) {
+        return [...this.data.sessions]
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+            .slice(0, limit);
+    }
+    getSession(sessionId) {
+        return this.data.sessions.find(s => s.id === sessionId) ?? null;
+    }
+    createSession(input) {
+        if (!this.getProject(input.projectId))
+            return null;
+        const ts = this.now();
+        const session = {
+            id: id('sess'),
+            projectId: input.projectId,
+            title: input.title?.trim() || 'New session',
+            summary: input.summary?.trim() ?? '',
+            createdAt: ts,
+            updatedAt: ts,
+        };
+        this.data.sessions.push(session);
+        this.save();
+        return session;
+    }
+    /** Bump a session's activity timestamp (and optionally its summary/title). */
+    touchSession(sessionId, patch) {
+        const session = this.data.sessions.find(s => s.id === sessionId);
+        if (!session)
+            return null;
+        if (patch?.title !== undefined)
+            session.title = patch.title.trim() || session.title;
+        if (patch?.summary !== undefined)
+            session.summary = patch.summary.trim();
+        session.updatedAt = this.now();
+        this.save();
+        return session;
+    }
+    // ── Onboarding settings ──────────────────────────────────────────────
+    getSettings() {
+        return { ...defaultSettings(), ...this.data.settings };
+    }
+    updateSettings(patch) {
+        const next = { ...this.getSettings(), ...patch };
+        if (patch.profile !== undefined)
+            next.profile = patch.profile.trim();
+        this.data.settings = next;
+        this.save();
+        return next;
+    }
+}