@geminilight/mindos 0.5.18 → 0.5.19

package/app/components/settings/KnowledgeTab.tsx

@@ -1,7 +1,7 @@
 'use client';
 
-import { useState, useSyncExternalStore } from 'react';
-import { Copy, Check, RefreshCw, Trash2 } from 'lucide-react';
+import { useState, useEffect, useCallback, useSyncExternalStore } from 'react';
+import { Copy, Check, RefreshCw, Trash2, Sparkles } from 'lucide-react';
 import type { SettingsData } from './types';
 import { Field, Input, EnvBadge, SectionLabel } from './Primitives';
 import { apiFetch } from '@/lib/api';
@@ -16,6 +16,38 @@ export function KnowledgeTab({ data, setData, t }: KnowledgeTabProps) {
   const env = data.envOverrides ?? {};
   const k = t.settings.knowledge;
 
+  // Guide state toggle
+  const [guideActive, setGuideActive] = useState<boolean | null>(null);
+  const [guideDismissed, setGuideDismissed] = useState(false);
+
+  useEffect(() => {
+    fetch('/api/setup')
+      .then(r => r.json())
+      .then(d => {
+        const gs = d.guideState;
+        if (gs) {
+          setGuideActive(gs.active);
+          setGuideDismissed(!!gs.dismissed);
+        }
+      })
+      .catch(() => {});
+  }, []);
+
+  const handleGuideToggle = useCallback(() => {
+    const newDismissed = !guideDismissed;
+    setGuideDismissed(newDismissed);
+    // If re-enabling, also ensure active is true
+    const patch: Record<string, boolean> = { dismissed: newDismissed };
+    if (!newDismissed) patch.active = true;
+    fetch('/api/setup', {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ guideState: patch }),
+    })
+      .then(() => window.dispatchEvent(new Event('guide-state-updated')))
+      .catch(() => setGuideDismissed(!newDismissed)); // rollback on failure
+  }, [guideDismissed]);
+
   const origin = useSyncExternalStore(
     () => () => {},
     () => `${window.location.protocol}//${window.location.hostname}`,
@@ -158,6 +190,36 @@ export function KnowledgeTab({ data, setData, t }: KnowledgeTabProps) {
           )}
         </div>
       </Field>
+
+      {/* Getting Started Guide toggle */}
+      {guideActive !== null && (
+        <div className="border-t border-border pt-5">
+          <SectionLabel>{t.guide?.title ?? 'Getting Started'}</SectionLabel>
+          <div className="flex items-center justify-between py-2">
+            <div className="flex items-center gap-2">
+              <Sparkles size={14} style={{ color: 'var(--amber)' }} />
+              <div>
+                <div className="text-sm text-foreground">{t.guide?.showGuide ?? 'Show getting started guide'}</div>
+              </div>
+            </div>
+            <button
+              type="button"
+              role="switch"
+              aria-checked={!guideDismissed}
+              onClick={handleGuideToggle}
+              className={`relative inline-flex h-5 w-9 shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring ${
+                !guideDismissed ? 'bg-amber-500' : 'bg-muted'
+              }`}
+            >
+              <span
+                className={`pointer-events-none inline-block h-4 w-4 rounded-full bg-white shadow-sm transition-transform ${
+                  !guideDismissed ? 'translate-x-4' : 'translate-x-0'
+                }`}
+              />
+            </button>
+          </div>
+        </div>
+      )}
     </div>
   );
 }

package/app/components/setup/StepAI.tsx

@@ -45,8 +45,16 @@ export default function StepAI({ state, update, s }: StepAIProps) {
             <ApiKeyInput
               value={state.provider === 'anthropic' ? state.anthropicKey : state.openaiKey}
               onChange={v => update(state.provider === 'anthropic' ? 'anthropicKey' : 'openaiKey', v)}
-              placeholder={state.provider === 'anthropic' ? 'sk-ant-...' : 'sk-...'}
+              placeholder={
+                (state.provider === 'anthropic' ? state.anthropicKeyMask : state.openaiKeyMask)
+                || (state.provider === 'anthropic' ? 'sk-ant-...' : 'sk-...')
+              }
             />
+            {(state.provider === 'anthropic' ? state.anthropicKeyMask : state.openaiKeyMask) && !(state.provider === 'anthropic' ? state.anthropicKey : state.openaiKey) && (
+              <p className="text-xs mt-1" style={{ color: 'var(--muted-foreground)' }}>
+                {s.apiKeyExisting ?? 'Existing key configured. Leave blank to keep it.'}
+              </p>
+            )}
           </Field>
           <Field label={s.model}>
             <Input

package/app/components/setup/index.tsx

@@ -129,9 +129,11 @@ export default function SetupWizard() {
     provider: 'anthropic',
     anthropicKey: '',
     anthropicModel: 'claude-sonnet-4-6',
+    anthropicKeyMask: '',
     openaiKey: '',
     openaiModel: 'gpt-5.4',
     openaiBaseUrl: '',
+    openaiKeyMask: '',
     webPort: 3000,
     mcpPort: 8787,
     authToken: '',
@@ -172,8 +174,10 @@ export default function SetupWizard() {
           webPassword: data.webPassword || prev.webPassword,
           provider: (data.provider === 'anthropic' || data.provider === 'openai') ? data.provider : prev.provider,
           anthropicModel: data.anthropicModel || prev.anthropicModel,
+          anthropicKeyMask: data.anthropicApiKey || '',
           openaiModel: data.openaiModel || prev.openaiModel,
           openaiBaseUrl: data.openaiBaseUrl ?? prev.openaiBaseUrl,
+          openaiKeyMask: data.openaiApiKey || '',
         }));
         // Generate a new token only if none exists yet
         if (!data.authToken) {

package/app/components/setup/types.ts

@@ -14,9 +14,11 @@ export interface SetupState {
   provider: 'anthropic' | 'openai' | 'skip';
   anthropicKey: string;
   anthropicModel: string;
+  anthropicKeyMask: string;   // masked existing key from server (display only)
   openaiKey: string;
   openaiModel: string;
   openaiBaseUrl: string;
+  openaiKeyMask: string;      // masked existing key from server (display only)
   webPort: number;
   mcpPort: number;
   authToken: string;

package/app/hooks/useAskModal.ts

@@ -0,0 +1,46 @@
+'use client';
+
+import { useSyncExternalStore, useCallback } from 'react';
+
+/**
+ * Lightweight pub/sub store for cross-component AskModal control.
+ * Replaces KeyboardEvent dispatch pattern with typed, testable API.
+ * No external dependencies (no zustand needed).
+ */
+
+interface AskModalState {
+  open: boolean;
+  initialMessage: string;
+  source: 'user' | 'guide' | 'guide-next';  // who triggered the open
+}
+
+let state: AskModalState = { open: false, initialMessage: '', source: 'user' };
+const listeners = new Set<() => void>();
+
+function emit() { listeners.forEach(l => l()); }
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+function getSnapshot() { return state; }
+
+export function openAskModal(message = '', source: AskModalState['source'] = 'user') {
+  state = { open: true, initialMessage: message, source };
+  emit();
+}
+
+export function closeAskModal() {
+  state = { open: false, initialMessage: '', source: 'user' };
+  emit();
+}
+
+export function useAskModal() {
+  const snap = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  return {
+    open: snap.open,
+    initialMessage: snap.initialMessage,
+    source: snap.source,
+    openWith: useCallback((message: string, source: AskModalState['source'] = 'user') => openAskModal(message, source), []),
+    close: useCallback(() => closeAskModal(), []),
+  };
+}

package/app/lib/agent/stream-consumer.ts

@@ -138,7 +138,9 @@ export async function consumeUIMessageStream(
           case 'tool-output-available': {
             const tc = toolCalls.get(chunk.toolCallId as string);
             if (tc) {
-              tc.output = typeof chunk.output === 'string' ? chunk.output : JSON.stringify(chunk.output);
+              tc.output = chunk.output != null
+                ? (typeof chunk.output === 'string' ? chunk.output : JSON.stringify(chunk.output))
+                : '';
               tc.state = 'done';
               changed = true;
             }
@@ -148,7 +150,7 @@ export async function consumeUIMessageStream(
           case 'tool-input-error': {
             const tc = toolCalls.get(chunk.toolCallId as string);
             if (tc) {
-              tc.output = (chunk.errorText as string) ?? 'Error';
+              tc.output = (chunk.errorText as string) ?? (chunk.error as string) ?? 'Tool error';
               tc.state = 'error';
               changed = true;
             }

package/app/lib/agent/tools.ts

@@ -4,6 +4,7 @@ import {
   searchFiles, getFileContent, getFileTree, getRecentlyModified,
   saveFileContent, createFile, appendToFile, insertAfterHeading, updateSection,
   deleteFile, renameFile, moveFile, findBacklinks, gitLog, gitShowFile, appendCsvRow,
+  getMindRoot,
 } from '@/lib/fs';
 import { assertNotProtected } from '@/lib/core';
 import { logAgentOp } from './log';
@@ -21,7 +22,13 @@ export function assertWritable(filePath: string): void {
   assertNotProtected(filePath, 'modified by AI agent');
 }
 
-/** Helper: wrap a tool execute fn with agent-op logging */
+/**
+ * Wrap a tool execute fn with agent-op logging.
+ * Catches ALL exceptions and returns an error string — never throws.
+ * This is critical: an unhandled throw from a tool execute function kills
+ * the AI SDK stream and corrupts the session message state, causing
+ * "Cannot read properties of undefined" on every subsequent request.
+ */
 function logged<P extends Record<string, unknown>>(
   toolName: string,
   fn: (params: P) => Promise<string>,
@@ -31,12 +38,12 @@ function logged<P extends Record<string, unknown>>(
     try {
       const result = await fn(params);
       const isError = result.startsWith('Error:');
-      logAgentOp({ ts, tool: toolName, params, result: isError ? 'error' : 'ok', message: result.slice(0, 200) });
+      try { logAgentOp({ ts, tool: toolName, params, result: isError ? 'error' : 'ok', message: result.slice(0, 200) }); } catch { /* logging must never kill the stream */ }
       return result;
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
-      logAgentOp({ ts, tool: toolName, params, result: 'error', message: msg.slice(0, 200) });
-      throw e;
+      try { logAgentOp({ ts, tool: toolName, params, result: 'error', message: msg.slice(0, 200) }); } catch { /* swallow — logging must never kill the stream */ }
+      return `Error: ${msg}`;
     }
   };
 }
@@ -47,12 +54,19 @@ export const knowledgeBaseTools = {
   list_files: tool({
     description: 'List files in the knowledge base as an indented tree. Directories beyond `depth` show "... (N items)". Pass `path` to list only a subdirectory, or `depth` to control how deep to expand (default 3).',
     inputSchema: z.object({
-      path: z.string().optional().describe('Optional subdirectory to list (e.g. "Projects/Products"). Omit to list everything.'),
-      depth: z.number().min(1).max(10).optional().describe('Max tree depth to expand (default 3). Directories deeper than this show item count only.'),
+      path: z.string().nullish().describe('Optional subdirectory to list (e.g. "Projects/Products"). Omit to list everything.'),
+      depth: z.number().min(1).max(10).nullish().describe('Max tree depth to expand (default 3). Directories deeper than this show item count only.'),
     }),
     execute: logged('list_files', async ({ path: subdir, depth: maxDepth }) => {
       try {
         const tree = getFileTree();
+
+        // Empty tree at root level → likely a misconfigured mindRoot
+        if (tree.length === 0 && !subdir) {
+          const root = getMindRoot();
+          return `(empty — no .md or .csv files found under mind_root: ${root})`;
+        }
+
         const limit = maxDepth ?? 3;
         const lines: string[] = [];
         function walk(nodes: Array<{ name: string; type: string; children?: unknown[] }>, depth: number) {
@@ -114,9 +128,9 @@ export const knowledgeBaseTools = {
 
   get_recent: tool({
     description: 'Get the most recently modified files in the knowledge base.',
-    inputSchema: z.object({ limit: z.number().min(1).max(50).default(10).describe('Number of files to return') }),
+    inputSchema: z.object({ limit: z.number().min(1).max(50).nullish().describe('Number of files to return (default 10)') }),
     execute: logged('get_recent', async ({ limit }) => {
-      const files = getRecentlyModified(limit);
+      const files = getRecentlyModified(limit ?? 10);
       return files.map(f => `- ${f.path} (${new Date(f.mtime).toISOString()})`).join('\n');
     }),
   }),
@@ -142,12 +156,12 @@ export const knowledgeBaseTools = {
     description: 'Create a new file. Only .md and .csv files are allowed. Parent directories are created automatically.',
     inputSchema: z.object({
       path: z.string().describe('Relative file path (must end in .md or .csv)'),
-      content: z.string().default('').describe('Initial file content'),
+      content: z.string().nullish().describe('Initial file content'),
     }),
     execute: logged('create_file', async ({ path, content }) => {
       try {
         assertWritable(path);
-        createFile(path, content);
+        createFile(path, content ?? '');
         return `File created: ${path}`;
       } catch (e: unknown) {
         return `Error: ${e instanceof Error ? e.message : String(e)}`;
@@ -283,11 +297,11 @@ export const knowledgeBaseTools = {
     description: 'Get git commit history for a file. Shows recent commits that modified this file.',
     inputSchema: z.object({
       path: z.string().describe('Relative file path'),
-      limit: z.number().min(1).max(50).default(10).describe('Number of commits to return'),
+      limit: z.number().min(1).max(50).nullish().describe('Number of commits to return (default 10)'),
     }),
     execute: logged('get_history', async ({ path, limit }) => {
       try {
-        const commits = gitLog(path, limit);
+        const commits = gitLog(path, limit ?? 10);
         if (commits.length === 0) return `No git history found for: ${path}`;
         return commits.map(c => `- \`${c.hash.slice(0, 7)}\` ${c.date} — ${c.message} (${c.author})`).join('\n');
       } catch (e: unknown) {

package/app/lib/fs.ts

@@ -59,7 +59,15 @@ function ensureCache(): FileTreeCache {
   if (isCacheValid()) return _cache!;
   const root = getMindRoot();
   const tree = buildFileTree(root);
-  const allFiles = buildAllFiles(root);
+  // Extract all file paths from the tree to avoid a second full traversal.
+  const allFiles: string[] = [];
+  function collect(nodes: FileNode[]) {
+    for (const n of nodes) {
+      if (n.type === 'file') allFiles.push(n.path);
+      else if (n.children) collect(n.children);
+    }
+  }
+  collect(tree);
   _cache = { tree, allFiles, timestamp: Date.now() };
   return _cache;
 }

package/app/lib/settings.ts

@@ -25,6 +25,15 @@ export interface AgentConfig {
   contextStrategy?: 'auto' | 'off'; // default 'auto'
 }
 
+export interface GuideState {
+  active: boolean;        // setup 完成时写入 true
+  dismissed: boolean;     // 用户关闭 Guide Card 时写入 true
+  template: 'en' | 'zh' | 'empty';  // setup 时写入
+  step1Done: boolean;     // 至少浏览过 1 个文件
+  askedAI: boolean;       // 至少发过 1 条 AI 消息
+  nextStepIndex: number;  // 0=C2, 1=C3, 2=C4, 3=全部完成
+}
+
 export interface ServerSettings {
   ai: AiConfig;
   agent?: AgentConfig;
@@ -36,6 +45,7 @@ export interface ServerSettings {
   startMode?: 'dev' | 'start' | 'daemon';
   setupPending?: boolean;  // true → / redirects to /setup
   disabledSkills?: string[];
+  guideState?: GuideState;
 }
 
 const DEFAULTS: ServerSettings = {
@@ -119,6 +129,23 @@ function parseAgent(raw: unknown): AgentConfig | undefined {
   return Object.keys(result).length > 0 ? result : undefined;
 }
 
+/** Parse guideState from unknown input */
+function parseGuideState(raw: unknown): GuideState | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const obj = raw as Record<string, unknown>;
+  if (obj.active !== true) return undefined;
+  const template = obj.template === 'en' || obj.template === 'zh' || obj.template === 'empty'
+    ? obj.template : 'en';
+  return {
+    active: true,
+    dismissed: obj.dismissed === true,
+    template,
+    step1Done: obj.step1Done === true,
+    askedAI: obj.askedAI === true,
+    nextStepIndex: typeof obj.nextStepIndex === 'number' ? obj.nextStepIndex : 0,
+  };
+}
+
 export function readSettings(): ServerSettings {
   try {
     const raw = fs.readFileSync(SETTINGS_PATH, 'utf-8');
@@ -134,6 +161,7 @@ export function readSettings(): ServerSettings {
       startMode:   typeof parsed.startMode   === 'string' ? parsed.startMode as ServerSettings['startMode'] : undefined,
       setupPending: parsed.setupPending === true ? true : undefined,
       disabledSkills: Array.isArray(parsed.disabledSkills) ? parsed.disabledSkills as string[] : undefined,
+      guideState: parseGuideState(parsed.guideState),
     };
   } catch {
     return { ...DEFAULTS, ai: { ...DEFAULTS.ai, providers: { ...DEFAULTS.ai.providers } } };
@@ -154,6 +182,7 @@ export function writeSettings(settings: ServerSettings): void {
   if (settings.mcpPort     !== undefined) merged.mcpPort     = settings.mcpPort;
   if (settings.startMode   !== undefined) merged.startMode   = settings.startMode;
   if (settings.disabledSkills !== undefined) merged.disabledSkills = settings.disabledSkills;
+  if (settings.guideState !== undefined) merged.guideState = settings.guideState;
   // setupPending: false/undefined → remove the field (cleanup); true → set it
   if ('setupPending' in settings) {
     if (settings.setupPending) merged.setupPending = true;

package/app/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/bin/cli.js

@@ -45,7 +45,7 @@ import { homedir } from 'node:os';
 
 import { ROOT, CONFIG_PATH, BUILD_STAMP, LOG_PATH, MINDOS_DIR } from './lib/constants.js';
 import { bold, dim, cyan, green, red, yellow } from './lib/colors.js';
-import { run } from './lib/utils.js';
+import { run, npmInstall } from './lib/utils.js';
 import { loadConfig, getStartMode, isDaemonMode } from './lib/config.js';
 import { needsBuild, writeBuildStamp, clearBuildLock, cleanNextDir, ensureAppDeps } from './lib/build.js';
 import { isPortInUse, assertPortFree } from './lib/port.js';
@@ -325,13 +325,7 @@ const commands = {
     const mcpSdk = resolve(ROOT, 'mcp', 'node_modules', '@modelcontextprotocol', 'sdk', 'package.json');
     if (!existsSync(mcpSdk)) {
       console.log(yellow('Installing MCP dependencies (first run)...\n'));
-      const mcpCwd = resolve(ROOT, 'mcp');
-      try {
-        execSync('npm install --prefer-offline --no-workspaces', { cwd: mcpCwd, stdio: 'inherit' });
-      } catch {
-        console.log(yellow('Offline install failed, retrying online...\n'));
-        run('npm install --no-workspaces', mcpCwd);
-      }
+      npmInstall(resolve(ROOT, 'mcp'), '--no-workspaces');
     }
     // Map config env vars to what the MCP server expects
     const mcpPort = process.env.MINDOS_MCP_PORT || '8781';

package/bin/lib/build.js

@@ -4,7 +4,7 @@ import { createHash } from 'node:crypto';
 import { resolve } from 'node:path';
 import { ROOT, BUILD_STAMP, DEPS_STAMP } from './constants.js';
 import { red, dim, yellow } from './colors.js';
-import { run } from './utils.js';
+import { run, npmInstall } from './utils.js';
 
 export function needsBuild() {
   const nextDir = resolve(ROOT, 'app', '.next');
@@ -105,12 +105,7 @@ export function ensureAppDeps() {
     ? 'Updating app dependencies (package-lock.json changed)...\n'
     : 'Installing app dependencies (first run)...\n';
   console.log(yellow(label));
-  try {
-    execSync('npm install --prefer-offline --no-workspaces', { cwd: resolve(ROOT, 'app'), stdio: 'inherit' });
-  } catch {
-    console.log(yellow('Offline install failed, retrying online...\n'));
-    run('npm install --no-workspaces', resolve(ROOT, 'app'));
-  }
+  npmInstall(resolve(ROOT, 'app'), '--no-workspaces');
 
   // Verify critical deps — npm tar extraction can silently fail (ENOENT race)
   if (!verifyDeps()) {

package/bin/lib/mcp-spawn.js

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { ROOT } from './constants.js';
 import { bold, red, yellow } from './colors.js';
+import { npmInstall } from './utils.js';
 
 export function spawnMcp(verbose = false) {
   const mcpPort = process.env.MINDOS_MCP_PORT || '8781';
@@ -11,19 +12,7 @@ export function spawnMcp(verbose = false) {
   const mcpSdk = resolve(ROOT, 'mcp', 'node_modules', '@modelcontextprotocol', 'sdk', 'package.json');
   if (!existsSync(mcpSdk)) {
     console.log(yellow('Installing MCP dependencies (first run)...\n'));
-    const mcpCwd = resolve(ROOT, 'mcp');
-    try {
-      execSync('npm install --prefer-offline --no-workspaces', { cwd: mcpCwd, stdio: 'inherit' });
-    } catch {
-      console.log(yellow('Offline install failed, retrying online...\n'));
-      try {
-        execSync('npm install --no-workspaces', { cwd: mcpCwd, stdio: 'inherit' });
-      } catch (err) {
-        console.error(red('Failed to install MCP dependencies.'));
-        console.error(`  Try manually: cd ${mcpCwd} && npm install\n`);
-        process.exit(1);
-      }
-    }
+    npmInstall(resolve(ROOT, 'mcp'), '--no-workspaces');
   }
   const env = {
     ...process.env,

package/bin/lib/utils.js

@@ -11,6 +11,29 @@ export function run(command, cwd = ROOT) {
   }
 }
 
+/**
+ * Run `npm install` with --prefer-offline for speed, auto-fallback to online
+ * if the local cache is stale or missing a required package version.
+ *
+ * @param {string} cwd - Directory to run in
+ * @param {string} [extraFlags=''] - Additional npm flags (e.g. '--no-workspaces')
+ */
+export function npmInstall(cwd, extraFlags = '') {
+  const base = `npm install ${extraFlags}`.trim();
+  try {
+    execSync(`${base} --prefer-offline`, { cwd, stdio: 'inherit', env: process.env });
+  } catch {
+    // Cache miss or stale packument — retry online
+    try {
+      execSync(base, { cwd, stdio: 'inherit', env: process.env });
+    } catch (err) {
+      console.error(`\nFailed to install dependencies in ${cwd}`);
+      console.error(`  Try manually: cd ${cwd} && ${base}\n`);
+      process.exit(err.status || 1);
+    }
+  }
+}
+
 export function expandHome(p) {
   return p.startsWith('~/') ? resolve(homedir(), p.slice(2)) : p;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminilight/mindos",
-  "version": "0.5.18",
+  "version": "0.5.19",
   "description": "MindOS — Human-Agent Collaborative Mind System. Local-first knowledge base that syncs your mind to all AI Agents via MCP.",
   "keywords": [
     "mindos",