Skip to main content

Module: editor / notes buffers

The emacs-like editing core: markdown/text buffers with command-palette-driven editing. Also the rendering target other modules use to open text (file explorer opens files into editor buffers).

Status: buffer panel + source model implemented (C1). The editor.buffer panel (CodeMirror 6) and the URI source model ship; openBuffer(source) opens (or focuses) a buffer for a note:/workspace-file: source, loading via the backend and saving back (notes carry the revision for conflict detection). The public command surface and the keybinding-service keymap (C3), agent tools (C4), and the editor.recentNotes dashboard widget (C5) all ship.

Engine: CodeMirror 6. Lean, extensible, and emacs-friendly — code-aware (syntax highlighting, markdown) without pulling in a full IDE. IntelliSense ships: the layered completion stack below (LSP spine + DB symbol index + curated imports) plus hover, diagnostics, go-to-definition, rename, and references. The CM6 keymap is exposed through the shell keybinding service so bindings stay rebindable — editing key handlers are never hardcoded in the component.

Contributions to the layout shell​

  • Panels: editor.buffer (one panel instance per open buffer, each in a window; merge windows to tab them). The shell owns tab UX, the editor owns content. The pane receives its source via pane params (usePaneParams); the instance id is derived from the source so reopening the same file/note focuses the existing buffer (generic windowing support added with openPanel(id, { instanceId, params })).

  • Commands (C3): editor.newNote (create + open a note, /new), editor.newBuffer (an untitled scratch file, /scratch — see Untitled buffers), editor.save (/save), editor.saveAs (/save-as), editor.saveAll (/save-all), editor.visualizeBuffer (open the active buffer in the visualizer, inferring the engine from its language). The /… names are the minibuffer slash forms (see windowing.mdx) — and because Save As is a dialogs.prompt(), it asks for the path in the minibuffer rather than a modal. editor.saveAs reaches the live CodeMirror view through a module-level setActiveSaveAs published by the focused BufferView, the same pattern the browser uses for its URL-bar focuser. mod+s is a default keybinding → editor.save routed through the shell keybinding service — the buffer has no hardcoded save handler, so the key stays rebindable. (editor.open quick-open is still to come.) ctrl+shift+space → editor.toggleSuggestions opens the completion popup, or closes it if it is open — a shell binding rather than a CodeMirror keymap so it is rebindable and listed with the rest, scoped when: textInput and acting on whichever view holds the caret (a buffer or a notebook cell). App-level keys route through the shell service; editor-internal keys are CodeMirror keymaps scoped to the view (they act on cursor/selection state, so a global command can't express them): Tab accepts an open completion popup, else opens one where completions could plausibly come from, else indents (Shift-Tab dedents); F12 go-to-definition and F2 rename (see the LSP section); Tab/Esc accept/dismiss inline autosuggest at higher precedence. Binding Tab is deliberate — basicSetup leaves it unbound for accessibility, which made it escape to the browser's focus traversal instead of indenting.

  • Services for other modules: editor.openBuffer(source, { language? }) is the public way any module shows editable text. Sources are URIs (note:, workspace-file:, gdrive:, github:, osfile: on desktop) so the buffer layer doesn't care where content lives; an optional language param highlights extensionless sources (notes). Reopening a source focuses its existing buffer rather than duplicating it (the pane's instance id is derived from the source URI), and opening from a blank, unmodified buffer reuses that pane in place — a placeholder editor holds nothing worth preserving, so notes opened from the Recent-notes region land in the editor you are looking at instead of splitting off a second one. Reuse goes through the frame engine's retargetPane (see windowing), which keeps the pane's area, tab position, and region strips. When there is nothing to reuse but the editor is already on screen, the new buffer opens as another tab in that same area (areaHostingView + openPaneInArea) — role-routed openPane would split off a fresh area instead, which meant every file clicked in the tree carved the frame up further. Only a first editor buffer takes new space. For richer cross-module use, the editor also registers an editor service on the registry (registry.getService('editor'), from service.ts) — openBufferFromContent (materialize content as a note or scratch/ file), getBufferContent (live, or the persisted bytes via loadSource when the tab is unmounted), peekBufferContent (sync, live-only), getBufferSelection (live-only by nature — a selection exists in a CodeMirror view and nowhere else, so this returns null for an unmounted tab rather than falling back to bytes), setBufferContent, getActiveBufferSource, and listBuffers. The visualizer uses this to bridge templates ⇄ buffers (see visualizer › Editor integration), and llama.cpp uses it to trace the selection through a model.

    Note what the service cannot reach: an untitled buffer. getActiveBufferSource is keyed by source URI and an unsaved buffer has none, so it is invisible to every cross-module consumer until it is saved. Callers should say that specifically rather than reporting "no open buffer" about a buffer that is plainly open.

  • Left region strip: editor.recentNotes (embedded) — the most-recently-updated notes (GET /notes); click a row to open it as a note: buffer, with a "New note" affordance. Refreshes on window focus so notes created/saved elsewhere appear.

Untitled buffers and language detection​

editor.newBuffer (/scratch) opens a buffer with no source — an unsaved file, not a note. It appears as untitled.md, and editor.buffer supported this shape all along (saveDir resolution, adoptSource retargeting on Save As); nothing opened it.

One resolver, editor/language.ts, answers "what language is this?" for both the grammar and the LSP. It used to be two maps that disagreed: a regex over the tab title chose the highlighting (JS/TS, Python, else Markdown — so a .rs or .cpp file rendered as Markdown and nothing said so), and a separate extension switch chose the LSP language id. Filename matching now comes from @codemirror/language-data, so the grammar set is CodeMirror's rather than a table we maintain, and each grammar is a dynamic import — nothing loads until a buffer needs it.

Precedence: a manual pin, then the opener's language hint, then the filename, then a content sniff, then Markdown.

The sniff (sniffLanguage, pure and unit-tested) runs only for a sourceless buffer. That gate is the whole design: a buffer with a name has already been told what it is, and a .py file momentarily holding prose is still Python. A shebang is decisive on its own; every other family needs two corroborating signals and a clear winner, because a language that flickers mid-word under the cursor is worse than one that arrives a beat late — import x alone is Python, JavaScript, Rust and Java at once. It reads a debounced snapshot (600ms), not every keystroke.

Saving pins the answer: Save As proposes an extension from the resolved language (a sniffed-Python scratch buffer offers .py), and once the file has a name the name decides. The buffer header carries a compact language control that reports the resolved language and lets you override it — the answer is sometimes a guess now, and a buffer silently highlighting as the wrong language with the wrong completions is exactly what saying so out loud prevents.

Adding a language is now two places, not three: language.ts and LSP_SERVERS in backend/modules/lsp/manager.py (which gained cpp and clangd).

Completion is no longer gated on the language server​

autocompletion() used to be configured in exactly one place — inside lspExtension — which meant only a workspace-file: in one of five languages had any completion source. A note, an unsaved buffer, a .json, a Drive file had none, even though the code_symbols index that would serve them was already built.

editor/completion.ts owns the stack instead, and the language server is one optional source among several. BufferView mounts it through its own compartment for buffers with no server; lspExtension calls the same builder with the server's source added.

One autocompletion() at a time, swapped in one transaction

CodeMirror merges configuration across live instances, but override is a replacing field it has no combiner for: two live instances that both set it do not degrade quietly, they make the dispatch throw Config merge conflict for field override. The LSP compartment and the standalone compartment are therefore configured from one predicate (usesLanguageServer) and are never both non-empty.

That predicate is not enough on its own, because the two compartments live in one buffer and a compartment is only as exclusive as the moment it is reconfigured. They must swap in the same transaction. They used to be reconfigured from two separate effects — the LSP one when the content arrived, the standalone one when the resolved language changed — and between the two, the stack resolved while the tab title was still the … placeholder (no language, so: standalone) was live alongside the one resolved from the loaded filename (gqa.py → python, so: LSP). The throw landed inside the load's .then, so the buffer's own .catch swallowed it into the status bar and the content transaction was rolled back with it: every source file opened from the Explorer came up blank.

Hence the load applies content on its own transaction first and reconfigures second, guarded — a buffer that loaded is more use with no completions than one that shows nothing.

Completing an import statement​

from <Tab> and from vllm import <Tab> ask questions the identifier prefix query cannot answer: the first has no prefix at all, the second wants one module's importable names rather than a global scan. editor/importContext.ts classifies the cursor (importContextAt, pure) and queries two routes:

RouteAnswers
GET /api/editor/complete/modulesModule names for a from / import statement.
GET /api/editor/complete/membersThe names importable from one module.

Both accept an empty prefix — unlike /complete, whose "no prefix, no rows" fast path is correct for the hot identifier lookup and would be the exact bug here. With no prefix the module query returns top-level modules only; listing every dotted submodule of every indexed package is thousands of rows and none of them is the question.

Two rules do real work:

  • The member query filters on imp, not module. For a method, module holds the class it belongs to (extract_packages stores member_of or module), so filtering on module would answer from vllm import … with LLM's methods and miss the package's own names. imp is by construction "the module this symbol can be imported from", and is empty for methods.

  • A member completion applies as a bare name, never through applyImport. We are already inside the import statement; routing through it would insert a second from vllm import LLM line above the one being typed.

  • A package with no rows of its own falls back to its submodules. imp is where a symbol is defined, never where it is re-exported from — transformers re-exports AutoModel out of transformers.models.auto — so the exact match answered from transformers import <Tab> with nothing while the index held 530 transformers symbols. Same for numpy and torch: for every package that assembles its public surface in __init__.py, which is most large ones. Only packages that define their names directly there (huggingface_hub, sympy) ever worked, which is what made this read as a flaky index rather than a structural miss.

    The fallback fires only when the exact match is empty, and that is the whole of its safety. vllm really does define LLM and really does not re-export LoRARequest, so blending submodule names into a package the index already describes correctly would offer an import that fails. Where there is nothing to be wrong about a guess costs nothing; where there is, the precise answer stands alone. Fallback rows carry their defining module in detail, so the guess is legible as one.

Modules rank by import depth first, so vllm beats vllm.lora.request — the same rationale that tiers the identifier query.

Opening the popup: three gestures, and why it needed all three​

An empty prefix is the case this whole path exists for, and it is also the one nothing can auto-trigger on — there is no word to match. So it is answered when the user asks (explicit), or at the one moment they are unambiguously waiting to be told:

  • Typing the space after the keyword. importContextAt reports justOpened when the cursor sits directly after import, from, a comma or an open paren, and one space at most. That is where VS Code opens its suggest widget, and where a person reaches for it. A second space, or a space following a half-typed name, is not that moment — opening on every space in the statement is what the empty-prefix guard originally prevented, and still does.
  • Tab — see below.
  • ctrl+shift+space, the editor.toggleSuggestions command. Deliberately not CodeMirror's own ctrl+space: keymap/reserved.ts lists that as the IME toggle on Windows and the input-source switch on macOS, both preventable: false. It is exactly the shape of binding that table exists to catch — it never reaches the page, and nothing says why. Toggling rather than only opening, because the same key then dismisses; a popup you can summon but must reach for Escape to close is half a binding. when: textInput scopes it to a focused editor surface, and focusedEditorView() resolves which one via EditorView.findFromDOM — a notebook has one view per cell, and the only one the command can mean is the one holding the caret.

Tab opens the popup​

Tab accepts an open popup, then tries to open one, then indents. The middle rung is the whole design risk: startCompletion returns true whether or not it finds anything, so calling it unconditionally would swallow indentation everywhere. tabStartCompletion therefore declines — falling through to indentWithTab — unless the selection is empty, the text before the cursor on this line is not entirely whitespace (that is indentation, unambiguously), and either a word character precedes the cursor or the cursor is in an import context. Ghost-text autosuggest keeps its Prec.highest Tab, so an inline suggestion is still accepted ahead of all of it.

Notebook cells get the same stack​

They did not. buildCompletion only ran inside lspExtension, and the Tab keymap was added by BufferView alone — so a notebook cell had no completion source unless a language server was attached, and no cell ever had the keymap. The visible symptom was the one this section is about: from transformers import in a cell offered nothing, Tab escaped to browser focus traversal instead of asking, and ctrl+space was eaten by the IME. Three separate gaps, one indistinguishable outcome.

Both halves now reach a cell, and which one is a real decision:

  • With a server, NotebookLspDoc.cellExtension returns the LSP extension plus completionKeymap.
  • Without one, EditorService.bareCompletion('python') returns the standalone stack plus the same keymap — that is every cell on a node with no Python server, every cell of a notebook opened before its absolute path resolves, and every cell during the seconds a cold server takes to come up.

They are alternatives and never both, for the reason in the caution above: two live autocompletion() instances make the dispatch that installs the second one throw. useNotebookLsp picks one and the cell's compartment swaps between them.

bareCompletion is on EditorService rather than deep-imported because the notebook kit is domain-neutral — it knows this contract and nothing else about this module.

bareCompletion and openNotebookLsp both return a promise. Their implementations are CodeMirror, and the service is registered at boot, so a static import in service.ts put all of CodeMirror (1.7 MB) on the boot path of every session, notebook or not. They import it on first use instead; useNotebookLsp hands a cell [] for the few milliseconds that takes, and disposes a handle that resolves after its effect was cleaned up.

Backend surface​

backend/modules/notes/ — note storage implemented: CRUD + search over backend-owned notes (GET/POST /notes, GET/PUT/DELETE /notes/{id}, GET /notes/search). Notes are identical everywhere; the editor opens them as note:<id> buffers. Autosave and conflict handling share one path: a save sends the base_revision the editor loaded, and a stale save returns 409 with the current note ({message, current}) so the client reconciles. Workspace-file read/write is the file explorer's GET /files/read / PUT /files/write (workspace-file: buffers), so the editor's buffer layer is URI-agnostic.

Read-only sources​

Some sources can be read but not written back. loadSource sets readOnly on the result and BufferView reconfigures a CodeMirror Compartment to EditorState.readOnly, replacing the Save button with a Read-only badge — so the absence of Save reads as a property of the source rather than a missing control. saveSource also throws for them, as a backstop against a caller going around the editor.

Enforcing it in the editor rather than at each call site is the point: a read-only buffer can never go dirty, so the close guard, the dirty marker, and the autosave path all no-op without needing to know about any particular provider.

SchemeBacked byNotes
gdrive:/<fileId>GET /files/read via the Drive virtual rootDocs exported to text, PDFs extracted; the title arrives with the content, since the path is an id
github:<owner>/<repo>@<ref>/<path>GET /connectors/github/…/fileopened from the GitHub viewer

Both inherit tabs, splits, find, and CodeMirror syntax highlighting, which is why neither the Drive mount nor the GitHub viewer ships a file viewer of its own.

Unsaved-changes guard on close​

Closing a buffer with unsaved edits prompts before discarding them, VS Code-style. The mechanism is a generic pane close guard in the frame engine (layout/close-guards.ts): a pane registers registerCloseGuard(instanceId, fn), and every close path — the group header's ✕, a tab's middle-click, the status bar, and LayoutController.closePane (so agent-driven closes are covered too) — routes through closePaneGuarded, which runs the guard and only dispatches REMOVE_PANE when it resolves true. BufferView registers a guard that, when the buffer is dirty, shows a dialogs.choice(...) prompt mirroring VS Code's exactly — "Do you want to save the changes you made to {title}?" / "Your changes will be lost if you don't save." — with Save (default) / Don't Save / Cancel. The save must succeed for the close to proceed; a failed or cancelled save keeps the buffer open. Like VS Code there's no separate "Save As…" button: a sourceless (untitled) buffer has nowhere to write, so its Save falls through to the Save As flow. dialogs.choice is the general multi-button dialog kind (alongside prompt/confirm); the <Dialogs /> component renders it.

Save As writes a file, not a note​

saveAs() always writes a workspace-file: — an untitled buffer is an unsaved file, and turning it into a note: (as this used to) put the work somewhere the file tree, git, and every other tool couldn't see it. Notes remain a first-class source; they're just something you open deliberately (/new), not what Save silently produces.

Three consequences worth knowing:

  • The destination is shown, not implied. The prompt is prefilled with the full absolute path and names the directory a bare name would land in. That directory is the first non-virtual workspace root, which is also what the backend anchors a relative path to (_resolve_relative in backend/modules/files/routes.py), so the path shown is the path written. The header carries the same information for every buffer: the file's full path, or — while untitled — the file it would become. With no workspace root configured at all (HORRIBLE_NO_DEFAULT_ROOT) Save says so instead of silently inventing a destination.
  • An untitled buffer adopts what it just wrote. It retargetPanes onto the new workspace-file: source, so the title bar, the tab, and every later mod+s follow the file — the buffer stops being "Untitled" the moment it stops being untitled. Retargeting rather than reopening keeps the pane's area, tab position and region strips. If that file is already open in another buffer the retarget is refused and the save is simply reported.
  • A buffer that already has a source keeps it. Save As there writes a copy to the new path and leaves the buffer pointed at its own source — which is what the close prompt needs, since re-pointing a closing buffer would be meaningless.

Closing the whole tab/window is guarded separately: dirty buffers flag themselves via setPaneDirty, and a beforeunload handler triggers the browser's native unsaved-changes prompt when anyPaneDirty() — the async choice dialog can't run during unload. (A native window-close confirmation in the desktop shell can gate on the same flag.)

Agent integration​

Status: implemented (C4). Declared on the editor.buffer panel; a live buffer controller registry (keyed by source URI) lets the type-level tools act on a specific open buffer. Verified live: the agent replaced an open buffer's content via editor.applyEdit. The editor exposes agent tools & getAgentContext:

  • Read (ungated): the active buffer's uri, full text, selection, dirty state, and live LSP diagnostics via the pane's getAgentContext() snapshot; plus the editor.getDiagnostics(uri) and editor.findReferences(...) read tools (the latter backed by LSP references).
  • Gated: editor.proposeEdit(uri, content), editor.applyEdit(uri, content), editor.rename(...) (LSP symbol rename, applied across files), and editor.save(uri), matched by the same filesystem Edit/files.write rules the tree uses. All auto-allow under the acceptEdits mode (Claude Code parity). See the permission system.

Because sources are URIs, the agent (like any module) shows editable text through the single editor.openBuffer(source) seam regardless of where the content lives.

Accept/decline proposed edits​

For any code change (format, rewrite, fix) the agent is steered to editor.proposeEdit rather than editor.applyEdit: instead of replacing the content outright, the buffer enters a diff/review state (a @codemirror/merge unifiedMergeView, original vs proposed, with per-chunk accept/reject in the gutter) and shows an Accept / Decline bar. Accept keeps the proposed content and marks the buffer dirty; Decline restores the pre-proposal text. The tool is in EDIT_SAFE_TOOLS because the in-editor review — not the permission gate — is the real safety boundary. Buffer controllers gain a propose(content) method (buffers.ts), driven from BufferView.tsx.

Inline autosuggest​

Opt-in, off by default — the editor.autosuggest setting. When on, after a typing pause the buffer shows ghost text at the cursor; Tab accepts, Esc dismisses. The suggestion is a prefix lookup into the DB symbol index (the tail of the single best-matching symbol for the token under the cursor — see Completion is a database lookup), not a model — so there's no round-trip latency and no hallucinated multi-line guesses. In-flight requests are debounced and cancelled on further typing; suggestions are suppressed while an edit proposal is under review. The CodeMirror extension is autosuggest.ts (ghost-text rendering + Tab/Esc), its fetch wired to dbGhostFetch in symbolCompletion.ts; toggled live via a compartment in BufferView.tsx. (The old model path — POST /api/agent/complete via providers.generate — is no longer in the completion loop; the model is reserved for the agent/orchestrator's deliberate edits.)

Language intelligence (LSP) & deeper agent editing​

Status: spine implemented (diagnostics, completion, hover, go-to-definition); the rest is design. The road from "buffer over a URI source" to a real code editor. The organizing idea is three stacked intelligence layers, each with a different latency and authority — they coexist (they don't replace one another), the way VS Code runs IntelliSense and Copilot side by side:

LayerSourceProvidesLatency
L1 localCodeMirror in the browsersyntax, brackets, search/replace, multi-cursor, indentationinstant
L1.5 DBbackend symbol index (SQLite)prefix completions (dropdown + ghost text) from a code_symbols tablesub-ms (indexed SQL)
L2 LSPbackend language-server processdiagnostics, type-aware/member completion, hover, go-to-def, references, rename, format~10–100 ms
L3 LLMbackend local modelagent/orchestrator edits (read, rename, alter, format selection) — not completion~0.1–n s

L1 is mostly CodeMirror's basicSetup. L1.5 is the DB symbol lookup that backs both completion surfaces (see below) — enriched by symdex: the package-symbol harvest projects each indexed API's signature and first docstring paragraph into code_symbols (doc column, source pkg:<dist>), so suggestions for framework symbols show a doc panel (info on the completion item) from the same single SQLite request — no embedding lookup ever sits on the keystroke path. L2 (LSP) covers the transport plus diagnostics, type-aware completion, hover, go-to-definition, rename, and references — with formatting layering onto the same pipe next. L3 (the model) is no longer in the completion loop: it drives the agent/orchestrator's deliberate edits, not typeahead.

Where the LSP runs: the backend, over a /ws lsp channel (implemented)​

Same rule as the agent orchestrator and the terminal PTY (see windowing and terminal): the browser can't spawn pylsp/typescript-language-server, both layouts must share one path, and with a remote backend the server must run where the files are.

The key design choice: the backend is a dumb JSON-RPC pipe, and the frontend is the LSP client. LspManager (backend/modules/lsp/manager.py, mirroring terminal/manager.py) spawns one server per session — chosen from a fixed languageId → command registry so the channel can't run arbitrary processes — and translates LSP's Content-Length framing ↔ discrete lsp-channel messages (start/rpc/stop ↔ started/rpc/exit/error). It never parses LSP semantics, so every future capability flows through the one pipe with no backend change. The server is spawned with a blocking subprocess.Popen and its stdio is pumped on a per-session daemon thread (reads relayed to the socket via run_coroutine_threadsafe), not asyncio.create_subprocess_exec — that asyncio API needs the ProactorEventLoop, but uvicorn runs the app on the SelectorEventLoop under --reload/--workers>1, where it raises NotImplementedError. The thread approach is loop-agnostic, so servers spawn automatically regardless of how the backend was launched (the terminal PTY is already loop-agnostic the same way — a PTY library with blocking reads offloaded via asyncio.to_thread). The frontend client lives in editor/lsp.ts (a CodeMirror extension wired through a compartment in BufferView.tsx): it renders publishDiagnostics via @codemirror/lint, serves textDocument/completion as a @codemirror/autocomplete source, shows textDocument/hover in a CodeMirror hover tooltip, binds F12 to textDocument/definition (same-file jumps move the cursor; cross-file jumps open the target via the editor's openBuffer and reveal it in the tree), and binds F2 to textDocument/rename. Request-shaped methods use JSON-RPC id correlation; same-file detection normalizes file:// URIs (servers vary in drive-letter case).

IntelliSense depth (implemented). Completion is a full IDE experience, not a bare name list: each item carries a documentation pane fetched lazily via completionItem/resolve when it's focused, and function/snippet items expand their placeholders (insertTextFormat: 2 → CodeMirror snippetCompletion). The list auto-opens on the server's trigger characters (e.g. . for members — captured from the initialize response's completionProvider.triggerCharacters), matching VS Code rather than waiting for the next word character. Both the doc pane and the hover tooltip render markdown (code blocks, bold, lists) through a small self-contained renderMarkdown helper — HTML-escaped first, so a docstring can't inject markup. Completion, resolve, and hover results are cached per document version and cleared on every debounced didChange, so re-opening a dropdown or re-hovering the same spot doesn't re-hit the server.

Servers spawn only when installed (else the editor silently degrades); each language maps to an ordered list of candidate servers — the first whose executable resolves wins. An executable resolves from the backend interpreter's own scripts directory first, then PATH. The scripts directory is not optional: the desktop supervisor launches .venv\Scripts\python.exe directly, which puts nothing on PATH, so a PATH-only lookup never found the dev dependency basedpyright and silently picked a globally installed pylsp instead — whose pyflakes reports !pip install in a notebook cell as invalid syntax, where basedpyright understands IPython lines. Python prefers basedpyright (basedpyright-langserver --stdio; MIT-licensed pyright fork with Pylance-grade completions, hover docstrings, and inlay hints — install with uv add --dev basedpyright) and falls back to pylsp (needs pyflakes/pycodestyle for diagnostics) when basedpyright isn't installed. Pylance itself is not an option — its licence restricts it to official Microsoft VS Code builds. typescript/javascript → typescript-language-server, and rust → rust-analyzer.

Which interpreter Python resolves against. stdlib (os., …) resolves from basedpyright's bundled typeshed, but third-party imports (torch, numpy, …) only complete when the server is pointed at a real interpreter whose site-packages holds them. The client tells basedpyright which one by answering workspace/configuration (it advertises workspace.configuration and replies with python.pythonPath + analysis knobs; other server→client requests get a null ack so nothing stalls). The path is resolved per file: the backend (backend/modules/lsp/pyenv.py, resolve_python_interpreter) walks up from the file for a .venv/venv (the app's venv convention, shared with training), else the system default interpreter (the py launcher on Windows, python3/python elsewhere — never the backend's own venv), and sends it on the started event. The editor.pythonPath setting overrides it. The interpreter is resolved when a buffer opens; changing the setting (or adding a venv) takes effect on reopen.

One shared server per interpreter+project. The frontend LSP client is pooled: buffers with the same ${languageId}::${projectRoot}::${interpreter} key share a single LspSession (editor/lsp.ts) — one start/sessionId, so the backend spawns one basedpyright indexed once for the whole project rather than one per file. The session owns the transport (a single JSON-RPC id space, workspace/configuration answering) and a document registry, routing each publishDiagnostics to the owning buffer by URI; the per-buffer plugin is a thin adapter (its own version/caches, diagnostics rendering, and the completion/hover/rename logic) that delegates requests to the session. Sessions are refcounted with a 60 s idle grace period, so switching tabs — which unmounts one buffer and mounts another — reuses the already-indexed server instead of respawning it; the server stops once no buffer has reused it. The project root and interpreter come from GET /api/editor/python-env (below), so files anywhere under a project pool together.

Notebook cells get the same language server​

Both notebook panes — the notebook module's and training's — attach a language server to their code cells, so a fine-tuning notebook completes against the torch/trl in its own project venv rather than against nothing.

A notebook is one document made of cells, not N little files: import torch in cell 1 is what makes torch. complete in cell 7. That is exactly what LSP 3.17's notebookDocument/* notifications describe, and basedpyright implements them, so editor/notebook-lsp.ts is a coordinator rather than a second client. One NotebookLspDoc per open notebook owns the session and the ordered cell array; each cell's CodeMirror view gets an ordinary lspExtension whose DocumentBinding routes sync through the notebook instead of through textDocument/*. Panes reach it through EditorService.openNotebookLsp and the useNotebookLsp hook — the notebook kit stays domain-neutral and never deep-imports the editor module.

Four things here are silent when wrong — the server stays up and answers, it just answers about a document that isn't yours. All four were measured against basedpyright 1.39.9 rather than read off the spec:

  • A cell document must use the vscode-notebook-cell: scheme. Under file: with a #cell0 fragment the server accepts the notebook and then resolves nothing: no diagnostics, empty completions, no error. The fragment itself is free-form, so it carries the nbformat cell id (stable across reordering).
  • A cell's edits must ride notebookDocument/didChange. A plain textDocument/didChange aimed at a cell URI is accepted and discarded, leaving the server analyzing the text the cell was opened with — which reads as "completions are stale" rather than as a sync bug.
  • Only code cells belong to the array. A markdown cell shifts every later cell's index, so a structural edit would land in the wrong place.
  • didOpen must carry the real cells. fetchPythonEnv is cached per directory, so on a second open the session is ready before React has run the effect that describes the cells; opening anyway sent cells: [], and a notebook the server believes is empty resolves nothing in any of it. The cells are the trigger for didOpen, not the session.

The pane must also hand the coordinator an absolute path. Both modules address notebooks relatively (to the notebook root, or to a training project), but the interpreter and project root are resolved by walking up from the file — so each pane joins its own root first. useNotebookLsp disables itself on a relative path rather than resolving some unrelated directory's environment.

Cells deliberately get no F12/F2: a definition or rename can land in another cell, and jumping there means mapping a cell URI back to a mounted editor the coordinator does not own. A key that silently does nothing across cells is worse than no key, so cross-cell navigation waits for the panes to expose a "reveal cell" callback. Hover still works, and the cell's docs chain narrows to the kernel source — the one thing a language server cannot do is ask the live kernel what the object actually is.

Framework auto-imports. basedpyright only auto-imports stdlib and workspace symbols — it never indexes installed third-party libraries (a documented limitation, unlike Pylance), so torch/numpy/pandas/… symbols aren't offered in a file until you've imported them. The editor ships a curated framework-import completion source (editor/pythonImports.ts) to fill the gap: typing a known symbol or alias (np, pd, plt, nn, DataFrame, Tensor, AutoModelForCausalLM, LLM, AsyncLLMEngine, …) offers it in any .py buffer, and accepting inserts the symbol and prepends the matching import (deduped, skipped when already imported). It merges into the same completion popup as the LSP and DB-symbol results but ranks below them (boost: -99), works even when no language server is running, and is toggled by the editor.frameworkImports setting (on by default).

Those suggestions are gated to installed packages and annotated with the version: a backend service (backend/modules/lsp/pyenv.py, GET /api/editor/python-env) resolves the interpreter, project root, and the installed pip versions of the tracked framework packages — cached per interpreter, so it's computed once and shared by every buffer. Only installed packages are suggested, and the popup shows the version (numpy 2.2.6). The Indexed packages settings section (editor/IndexedPackages.tsx) lists those packages × versions for the active interpreter and persists a version snapshot (editor.indexedPackages), flagging when the installed versions drift from it — so it's clear which library versions intellisense is running against.

Completion is a database lookup​

Typeahead completion — both the dropdown popup and the inline ghost text — is a fast prefix lookup into a symbol database, never a model. The model (the agent/orchestrator) is reserved for deliberate edits (read editors, rename, alter code, format the selection); it is not in the completion loop, so completion has no model latency.

  • The index. A code_symbols table (symbol, lang, kind, detail, module, source, freq, doc, imp) in the built-in .data/app.db SQLite file — the same file the library catalog uses, so the app database connection can browse it. Indexed on (lang, symbol) so symbol LIKE 'req%' is sub-millisecond (backend/modules/lsp/symbol_store.py).
  • What's indexed. Three corpora, all ast-parsed and never imported:
    1. Python builtins + keywords, seeded once.
    2. The whole Python standard library and the installed framework packages, harvested by symdex into sources std:<module> / pkg:<dist> with a real signature and first docstring paragraph. This is what makes pathlib.Path, json.dumps, torch.Tensor, trl.SFTTrainer, … complete with documentation offline. Built once in the background (see Triggers).
    3. Each open buffer's own symbols — defs, classes, params, assigned names, imported names (backend/modules/lsp/symbol_index.py). The client pushes a buffer to POST /api/editor/symbols/index on open and on a debounced idle after edits; each push replaces that source's rows so its symbols never go stale. Rows for a file that no longer exists are purged at startup, so a deleted buffer's symbols don't linger.
  • The lookup. GET /api/editor/complete?lang=&prefix=&limit= runs the ranked prefix query. Ranking is tiered — your own buffers and the builtins first, then importable indexed symbols, then indexed methods (which a bare-prefix query is almost never after) — and within a tier prefers the shallowest import path, so json.dumps beats xmlrpc.client.dumps and numpy.array beats numpy.core.multiarray.array. Rows are grouped by (symbol, module), so the Path in pathlib and the Path in fastapi.params stay separate suggestions instead of blending into one.
  • Accepting inserts the import. An indexed row carries imp, the module the symbol is importable from (empty for methods, which aren't). Accepting such a completion inserts the symbol and its from <module> import <name> line, deduped and placed after the docstring and existing imports — the same applyImport mechanism the curated framework source uses, now driven by the real index.
  • One merged source, deduped against the server. The LSP source and the offline sources are composed into a single @codemirror/autocomplete source (mergedSource in lsp.ts) rather than registered in parallel. basedpyright ships typeshed, so once warm it already offers stdlib auto-imports; the merge lets the server win any label it provides and the indexed sources fill in only what it didn't, instead of listing every stdlib symbol twice.

Division of labor: L1.5 (DB) drives identifier-prefix completion + ghost text; L2 (LSP) drives type-aware / member completion; the framework-import source adds not-yet-imported library symbols; the model does none of it.

The cold start​

Spawning a language server, running initialize, and indexing a project takes seconds. Completion requests that arrive in that window used to return nothing, with no retry — so a freshly-opened buffer felt like it had no intellisense at all. Two things close that gap:

  • A completion request waits for a still-warming server, bounded by editor.completionWarmupMs (2000ms default, 0 to never wait). The offline sources have already resolved, so this only delays the server's contribution.
  • When the session finishes initializing, the client re-opens the completion list if the buffer is focused and the cursor is mid-word (session.onReady in lsp.ts), so a popup dismissed during the cold start comes back with the full results.

Intellisense settings​

Declared in the editor manifest and edited on the settings page. The language-server ones are captured when a buffer opens (the LSP extension lives in a compartment reconfigured on load), so a change takes effect for buffers opened after it. The last two below reach the live completion compartment instead and apply immediately.

SettingDefaultWhat it does
editor.indexedSymbolstrueMerge the indexed stdlib/package symbols into the popup, with signatures, docstrings, and automatic import insertion.
editor.completionWarmupMs2000How long a completion request waits for a still-starting language server before falling back to the instant indexed results. 0 never waits.
editor.changeDebounceMs300Wait after you stop typing before pushing the buffer to the server. Lower = fresher completions and diagnostics, more traffic.
editor.diagnosticstrueRender server errors/warnings in the gutter. The agent's editor.getDiagnostics still sees them when this is off.
editor.hovertrueShow the server's type/documentation tooltip on hover.
editor.pythonPath''Interpreter basedpyright analyzes against. Empty auto-detects a project .venv or system Python.
editor.frameworkImportstrueThe curated framework-import suggestions (see above).
editor.autosuggestfalseInline ghost-text completions from the local model.
editor.completionTriggerautoWhen the popup opens. auto opens it as you type (and on Tab/Ctrl-Space); manual keeps the buffer quiet until you ask. Tab still indents wherever there is nothing to complete. Applies live.
editor.importCompletionstrueComplete module names and members inside import statements, including on an empty prefix. Python only. Applies live.

A small by-URI registry (editor/lsp-registry.ts, keyed by the buffer's workspace-file: source URI — the same key the agent edit tools use) is the seam the agent reaches LSP through without touching CodeMirror: the live client records its latest diagnostics there and registers a handle exposing rename, find-references, and ghost-text grounding. A rename's WorkspaceEdit is applied across files — the live buffer is edited in place, other open buffers update through their controller, and closed files are loaded, edited, and saved.

The buffer — not the file on disk — is the source of truth while open, so the document-sync lifecycle matters. To optimize WebSocket traffic, document updates (didChange) are debounced by 300ms. However, to prevent position mismatch errors, any LSP request (hover, completion, definition, rename, references, grounding) will synchronously flush pending changes to the server beforehand. Furthermore, to avoid race conditions when the server is spawning, didOpen fetches the document's content dynamically at the moment of initialization rather than caching a stale version.

workspace-file: URIs map directly to real paths the server roots on; note: and osfile: get no LSP (only workspace-file: buffers with a known language do). Sync is full-text didChange (debounced 300ms or flushed on demand) — simple and correct; incremental is a later optimization. LSP capabilities map onto CodeMirror: completion → autocomplete source, publishDiagnostics → linter, hover → tooltip, definition → a jump that opens a workspace-file: buffer and reveals it in the tree. Additionally, autocomplete requests include a completion context containing the trigger kind and trigger character (e.g. .) to help the language server filter candidates accurately.

Range edits replace full-content edits​

editor.proposeEdit/applyEdit today take the whole new buffer. That doesn't scale to real files: it blows a local model's context and forces it to reproduce code verbatim. The plan is anchored, search/replace-style edits (proposeEdit(uri, edits: {find, replace}[]), full-content kept as a fallback). The existing accept/decline unifiedMergeView renders them per-chunk unchanged — only the tool payload narrows from "whole doc" to surgical edits. This is what lets the agent edit a large file with a small local model.

Ghost text (superseded: was LSP-grounded model, now a DB lookup)​

Status: reworked. Ghost text used to be a model completion (/agent/complete via providers.generate), grounded with LSP context to reduce hallucination. It was too slow — a full model round-trip per suggestion. It is now a prefix lookup into the DB symbol index (dbGhostFetch in symbolCompletion.ts → GET /api/editor/complete): the tail of the single best-matching symbol for the token at the cursor, or nothing when there's no confident match. No model, no round-trip. See Completion is a database lookup. The split is now: L1.5 (DB) drives identifier completion + ghost text, L2 (LSP) drives type-aware/member completion, and the model drives only the agent/orchestrator's deliberate edits (below). The /agent/complete endpoint + _grounding remain in the agent module but are no longer wired to the editor.

The agent reading & watching the buffer​

  • Passive (read) — implemented: the buffer's LSP diagnostics are in getAgentContext (the buffer snapshot's diagnostics) and behind a editor.getDiagnostics(uri) read tool, so the agent sees the errors it causes and self-corrects — the highest-leverage agent-editor upgrade. 1-based line/column, plain severity.
  • Agent-as-LSP-client tools — implemented: editor.rename and editor.findReferences backed by LSP rename/references — correct, scope-aware cross-file edits instead of regex. Both take a symbol name (first occurrence) or an explicit 1-based line/column. Reads (getDiagnostics/findReferences) ungated; rename is gated like applyEdit (in EDIT_SAFE_TOOLS, so it auto-allows under acceptEdits) — it is a language-server symbol rename, a scoped refactor, not a filesystem rename. editor.format (LSP formatting) is the remaining one.
  • Proactive (opt-in) — design: an editor.agentWatch mode where each didChange → publishDiagnostics with errors pings the orchestrator with the diagnostic + surrounding code; it may proposeEdit a fix (suggest, never auto-apply). Gated, off by default.

Browser vs desktop​

Editing notes and workspace files is identical in both layouts. The difference is which files you can reach:

ConcernBrowserDesktop
Notesfullfull
Workspace filesfull — read/write through the backend FS APIfull — same path
Arbitrary OS filesno (fs.nativeDialogs absent; File System Access API deliberately not used for v1)native open/save dialogs via the shell; opened as osfile: buffers
Drag a file onto appimports content as a new noteopens the file as a buffer

Remember the layout-shell rule: with a remote backend in the browser, "workspace files" are files on the backend host.