feat: initial Lam Agent extension for Vicinae
Agentic AI chat inside the Vicinae launcher, powered by Ollama. - chat: the search bar is the composer (Return sends), cmd+return opens a multi-line composer, answers stream into a markdown detail panel, the newest turn renders first, and Tab reaches a conversation switcher in the search bar accessory - sessions: browse, reopen, copy, and delete past conversations - setup: verifies the Ollama connection and lists the models the key can actually reach, rather than trusting a hand-typed model name - tools: get_datetime, get_location, web_search, web_fetch. All read-only, and the tool-calling loop is capped at 5 rounds Notes on two constraints that shaped the design: The search bar is single-line and there is no API to change it, so "Return sends" and "cmd+return inserts a newline" cannot both live in one field. They are split across the search bar and a pushed Form instead. An extension can read preferences but cannot write them, so setup hands over the exact model name to paste rather than saving it. The logic layer (ollama, agent, tools, location, history, markdown) holds no Vicinae imports and is unit tested without a runtime; a test enforces that boundary. 77 tests cover NDJSON chunk-boundary parsing, the tool loop, session caps, and timezone handling.
This commit is contained in:
@@ -1,3 +1,176 @@
|
||||
# ned-agent-vicinae
|
||||
# Lam Agent for Vicinae
|
||||
|
||||
test
|
||||
Agentic AI chat inside the [Vicinae](https://vicinae.com) launcher, powered by [Ollama](https://ollama.com).
|
||||
|
||||
Hit a global shortcut, type a question, get a streamed answer — without leaving whatever you were doing.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
> **Status:** early. Chat, streaming, persistent sessions and the web tools work. Anything that *acts* on your machine (opening links, clipboard, launching apps) is deliberately not here yet — see [Roadmap](#roadmap).
|
||||
|
||||
---
|
||||
|
||||
## What it does
|
||||
|
||||
- **Global hotkey, instant input.** Bind a shortcut to the chat command and the search bar is focused before you finish the keystroke.
|
||||
- **Streaming answers.** Tokens render as they arrive, in a markdown side panel.
|
||||
- **Persistent conversations.** Every chat is saved locally and can be reopened later.
|
||||
- **Tools.** Lam decides when to call them — current time, location context, web search, and page fetching.
|
||||
- **Chat only.** Lam answers questions. It does not touch your files or run commands.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Vicinae with the extension runtime enabled (Node.js 20+ on `PATH`)
|
||||
- An [Ollama](https://ollama.com) account and API key — [create one here](https://ollama.com/settings/keys)
|
||||
|
||||
Ollama Cloud is the default. A local Ollama server works too: point **Ollama Host** at `http://localhost:11434`. Note that the web tools are a cloud feature and are not available from a local server.
|
||||
|
||||
## Install
|
||||
|
||||
```sh
|
||||
npm install
|
||||
npm run dev # build + hot reload into a running Vicinae
|
||||
```
|
||||
|
||||
Or build once:
|
||||
|
||||
```sh
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
Setup is two prompts on first launch, then one command you can revisit any time.
|
||||
|
||||
1. **The API key.** Vicinae prompts for required preferences before a command runs, so the very first launch asks for your Ollama API key.
|
||||
2. **The model.** The next prompt asks which model to use — type it exactly, e.g. `deepseek-v4.1-flash:cloud` or `gpt-oss:120b`.
|
||||
3. **`Set Up Lam Agent`** verifies the connection, lists every model your key can actually reach, and copies a model name to the clipboard so you can paste it into preferences.
|
||||
|
||||
To change the model later, either edit the **Model** preference directly, or run **Set Up Lam Agent** and copy the name of a model you would rather use.
|
||||
|
||||
> An extension can read preferences but not write them, which is why setup hands you the exact name to paste rather than saving it for you. It also means the model list can never drift out of sync with your account.
|
||||
|
||||
## Keyboard shortcuts
|
||||
|
||||
| Keys | Action |
|
||||
| --- | --- |
|
||||
| `↩` | Send the message in the search bar |
|
||||
| `⌘ ↩` | Compose a longer, multi-line message |
|
||||
| `Tab` | Jump to the conversation switcher in the search bar |
|
||||
| `⌘ N` | New chat |
|
||||
| `⌘ ⇧ C` | Copy the highlighted answer |
|
||||
| `⌘ ⌫` | Delete a conversation (in **Chat Sessions**) |
|
||||
|
||||
Inside the composer: `↩` inserts a new line, `⌘ ↩` sends.
|
||||
|
||||
### Suggested global shortcuts
|
||||
|
||||
Assign these in **Vicinae Settings → Extensions → Lam Agent**, or bind them in your compositor/window manager with [deeplinks](https://docs.vicinae.com/deeplinks):
|
||||
|
||||
```sh
|
||||
vicinae 'vicinae://launch/lam-agent/chat?toggle=true'
|
||||
```
|
||||
|
||||
```ini
|
||||
# Hyprland
|
||||
bind = $mainAlt, Space, exec, vicinae 'vicinae://launch/lam-agent/chat?toggle=true'
|
||||
|
||||
# niri
|
||||
Mod+Shift+Space repeat=false { spawn "vicinae" "vicinae://launch/lam-agent/chat?toggle=true"; }
|
||||
```
|
||||
|
||||
`fallbackText` pre-fills the prompt, which makes a handy "ask about this" command:
|
||||
|
||||
```sh
|
||||
vicinae 'vicinae://launch/lam-agent/chat?fallbackText=summarise%20this'
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Purpose |
|
||||
| --- | --- |
|
||||
| **Chat with Lam** | The chat surface. Bind this to your global shortcut. |
|
||||
| **Chat Sessions** | Browse, reopen, and delete past conversations. |
|
||||
| **Set Up Lam Agent** | Verify the connection and list available models. |
|
||||
|
||||
## Configuration
|
||||
|
||||
| Preference | Default | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Ollama API Key** | — | Required. Stored by Vicinae as a password preference. |
|
||||
| **Model** | — | Required. Any model your key can reach. |
|
||||
| **Ollama Host** | `https://ollama.com` | Set to `http://localhost:11434` for a local server. |
|
||||
| **System Prompt** | Lam's default | Replaces the built-in prompt entirely. |
|
||||
| **Web Tools** | on | Enables `web_search` and `web_fetch`. |
|
||||
| **Reasoning Effort** | Off | `low`/`medium`/`high` for models that support thinking. |
|
||||
|
||||
## Tools
|
||||
|
||||
Lam calls these on its own when they would improve an answer. All four are read-only.
|
||||
|
||||
| Tool | What it does |
|
||||
| --- | --- |
|
||||
| `get_datetime` | Current local date, time, weekday, timezone, and UTC offset. |
|
||||
| `get_location` | Timezone, UTC offset, locale, region, and city. |
|
||||
| `web_search` | Searches the web; returns titles, URLs, and snippets. |
|
||||
| `web_fetch` | Fetches one page and returns its content as markdown. |
|
||||
|
||||
`get_location` is derived from your device timezone rather than GPS or an IP lookup, so no third-party geolocation service sees your address. Treat it as "which region am I in", not "where am I".
|
||||
|
||||
Web search results and fetched pages can be large. Lam truncates them before they reach the model, and gives up after 5 rounds of tool calls rather than looping.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
src/
|
||||
chat.tsx # "chat" command entrypoint — thin wrapper
|
||||
sessions.tsx # browse, reopen, delete conversations
|
||||
setup.tsx # connection check + live model list
|
||||
lib/
|
||||
ollama.ts # the only file that talks HTTP
|
||||
agent.ts # the tool-calling loop
|
||||
tools.ts # tool schemas + dispatch
|
||||
sessions.ts # LocalStorage persistence
|
||||
history.ts # turns -> API messages
|
||||
location.ts # time/place, derived locally
|
||||
markdown.ts # turn -> detail-panel markdown
|
||||
preferences.ts # preferences, normalised
|
||||
hooks/useChat.ts # the chat state machine
|
||||
components/ChatView.tsx # the chat surface
|
||||
components/ComposeForm.tsx
|
||||
```
|
||||
|
||||
A few decisions worth knowing about before you change things:
|
||||
|
||||
**The search bar is the composer.** It is the only always-focused text input in a `List`, which is what makes "hotkey, then just type" work. It is also single-line and there is no API to change that, which is the entire reason `ComposeForm` exists. `filtering` is off, because this list is a transcript — the builtin fuzzy filter would hide turns as you type a question.
|
||||
|
||||
**Every transcript row shares one primary action**, so `↩` always sends whatever is in the search bar regardless of which row is selected. That is what makes the window feel like a single input box rather than a menu.
|
||||
|
||||
**Turns render newest first**, so the answer you just asked for is nearest the search bar instead of below the fold.
|
||||
|
||||
**Streamed deltas are buffered in refs and flushed to state on a timer** (`FLUSH_INTERVAL_MS`). Re-rendering the transcript per token makes the launcher visibly janky.
|
||||
|
||||
**The logic layer has no Vicinae imports.** `agent.ts`, `ollama.ts`, `tools.ts` and friends are plain TypeScript, which is why they unit test without a runtime. A test enforces this.
|
||||
|
||||
**Sessions are capped twice over** — per turn and per session — because `LocalStorage` has no documented ceiling.
|
||||
|
||||
## Development
|
||||
|
||||
```sh
|
||||
npm run dev # watch + reload
|
||||
npm run typecheck
|
||||
npm run lint:code
|
||||
npm test
|
||||
```
|
||||
|
||||
`vicinae-env.d.ts` is generated by the toolchain and gitignored; `src/lib/preferences.ts` declares the preference shape by hand so the logic layer needs no codegen step.
|
||||
|
||||
## Roadmap
|
||||
|
||||
- **Actions.** Opening links, clipboard access, launching apps. These need an approval step first — an assistant that can silently act on your machine is a different risk profile from one that answers questions, and this release does not pretend otherwise.
|
||||
- **`@` mentions** for files and clipboard content.
|
||||
- **Per-conversation model** overrides.
|
||||
- **Image input**, which Ollama's chat API already supports.
|
||||
|
||||
## License
|
||||
|
||||
MIT — see [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user