Jaroslav Beneš
00ce04addf
Six things, all found by using the thing rather than by reading it. The scope menu only appeared once a chat existed, on the reasoning that there was no row to post to. True, and the wrong conclusion: the harness puts a tool's guidance in front of the model the moment the tool is offered, so the menu could not be reached until after the model had been told how to keep notes and handed the tools to do it -- and switching it off then does not un-send that turn. It is on the new-chat screen now and writes nothing: `_scope_context` builds a stand-in Chat, which is `draft.as_chat`'s trick again, and the switches ride along with the first message. Checked means on and a browser submits only the ticked boxes, so every gate also renders a hidden input naming it and `start_chat` subtracts one list from the other; inverting the control would read backwards under a menu that says everything is on unless you say otherwise. Only the off ones are written, because absent means on and one representation of it is what keeps "why is this off?" to a single answer. Nothing is validated against the offered set, since scope_json narrows after every gate -- naming a gate that was never offered switches off something that was not on. Then the scheduling instructions, audited against a 4B model on this machine rather than against my own reading of them. Ten realistic requests, ten compiled, twice over -- so the prompt is sound. What was not sound was `describe`, which built a phrase by joining fragments and read "Every the 1st at 09:00" for the commonest monthly schedule there is, and "Every of January" for a month with no day. That string is the whole of what somebody sees before approving a schedule and the whole of what the model is told about its own chat, so a phrase nobody can parse is a review step nobody performs. It reads as English now, collapses Monday-to-Friday to "every weekday" and seven days to "every day", and every case in the test is a rule that model actually produced. The one mistake it made was naming Wednesday for "every other tuesday", so the weekday numbering is spelled out rather than left as "0-6, Monday is 0": getting that wrong is the error here that still looks like a working schedule. Roughly one call in six also came back empty -- a local runner swapping models under the request will do that -- so an unusable reply is asked for once more before giving up. Not on an LLMError: an endpoint that refused will refuse again, and the reader is better served by the form than by waiting twice for the same answer. Canvas asked for a typed path, which was the last control in the application expecting somebody to remember an absolute path on another machine -- the same complaint the folder page's directory field answered with a picker. /browse takes pick=file and the same fragment makes files buttons, because a second copy of that listing is a second place for the path arithmetic to be got subtly differently. The button carries data-canvas-open rather than an hx-post since the path is not known until the dialog closes, and ui.js posts it through htmx.ajax so the response lands in the panel exactly as every other canvas action's does. The key is `agent:<path>`, so a file opened by hand and one opened by the model are one tab rather than two spellings of it. The tabs already existed and already closed; they now square off at the bottom and the active one takes the body's background, so which is selected is structural rather than a tint nobody can see in a theme they did not choose. Highlighting was already there for every language named and is checked for fifteen of them. Three smaller ones. Tabs kept their scroll position, so switching from a long panel to a short one left the browser clamping to that panel's bottom: the end of it above a screen of nothing, which reads as a page that failed to load. Nothing in CSS can reset a scroll position. The sidebar's footer and the composer sit either side of one vertical edge and were both content-sized, so their top borders met it at different heights and read as one line that had been broken -- `--footer-height` is a calc of the pieces the footer is built from, applied as a min-height to both, which is exactly what `--header-height` already does at the top of the shell. And "Add a workflow" sat flush against the list it adds to, stated as an adjacency because `.btn-row` is right to carry no margin everywhere else it appears. Both pieces of JavaScript were driven under a DOM stub before committing, which is how the tab listener's delegation and the canvas button's six behaviours were checked at all -- `node --check` parses a file that does nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
475 lines
27 KiB
Markdown
475 lines
27 KiB
Markdown
# LLeMbas — plan and status
|
|
|
|
Where the project is, what is deliberately not built yet, and the decisions
|
|
that would be expensive to revisit. Kept current as work lands; the detail of
|
|
*how* things work lives in [`CLAUDE.md`](CLAUDE.md).
|
|
|
|
**Status:** usable daily. Streaming chat, attachments, reasoning, tool calling
|
|
with web search, custom HTTP tools and MCP servers, agent chats that work on a
|
|
machine over SSH, a knowledge library, notes, memory and skills, speech in and
|
|
out, image generation over ComfyUI, users and groups, model administration,
|
|
installable as an app, reports, messages, and scheduled work that runs on its
|
|
own. 1824 tests, `ruff` clean.
|
|
|
|
---
|
|
|
|
## The shape of it
|
|
|
|
A self-hosted web UI for OpenAI-compatible endpoints, written in Python, themed
|
|
after Middle-earth.
|
|
|
|
| | |
|
|
|---|---|
|
|
| Stack | FastAPI + Jinja + htmx + a little Alpine |
|
|
| Build step | none — no Node, no npm, no CDN at runtime |
|
|
| Database | SQLite, schema synchronised additively at startup |
|
|
| Deployment | systemd unit + nginx vhost, one worker |
|
|
|
|
These are load-bearing. Dropping the no-build rule or moving off SQLite would
|
|
be a different project, not a refactor.
|
|
|
|
---
|
|
|
|
## Done
|
|
|
|
### Chat
|
|
- [x] Streaming replies over server-sent events
|
|
- [x] **Markdown renders progressively** — re-rendered whole every 100ms rather
|
|
than appending tokens, because a list or code fence is only correct once
|
|
its context exists
|
|
- [x] Syntax highlighting (Pygments), sanitised with nh3
|
|
- [x] **Generation runs in the background** — a task, not the request. Navigate
|
|
away, open another chat, close the tab: the reply keeps being written and
|
|
reattaching replays the whole state
|
|
- [x] **Stop** — the send button becomes Stop while writing; what arrived is kept
|
|
- [x] **Rewind** — edit one of your own turns and the conversation runs on from
|
|
there. Truncates rather than branching
|
|
- [x] **Chat titles that fit the chat** — an ordinary chat is named by a model
|
|
from the first exchange, an agent chat from its opening words alone, which
|
|
are already an objective. Renameable from the heading and from the sidebar
|
|
row; one response updates both
|
|
- [x] Chats created on first message, so an abandoned composer leaves nothing
|
|
- [x] **Unread indicator** — a green dot and a toast when a reply lands while
|
|
you were elsewhere
|
|
- [x] **A reply that started without you asking still arrives** — the open chat
|
|
page polls for turns it has not got, so a background job waking the model
|
|
appears where you are looking instead of only after a reload. Quiet while
|
|
a reply is streaming, since that reply delivers its own bubbles
|
|
- [x] **A turn nobody typed says so** — a background job's completion is a user
|
|
turn on the wire, because the request needs one, and a machine event in
|
|
the transcript: its own icon and name, no pencil, and no claim that you
|
|
sent it
|
|
- [x] **Folders that carry something** — arbitrarily nested, with a name, a
|
|
description, a system prompt inherited by the chats inside them, and seeds
|
|
for the model, the kind and the agent target. Deleting one keeps the chats
|
|
- [x] **The sidebar splits Chat and Agent** — a switch below the pinned models,
|
|
stored on the account, filtering the folder tree as well as the loose
|
|
chats
|
|
- [x] **A reply reads as the sequence it was** — thinking, prose, a tool call,
|
|
more prose, in the order they happened, rather than three stacked zones
|
|
with every tool block in the middle. Marks on the row index the three
|
|
stores; a reply written before them renders exactly as it always did
|
|
- [x] **Blocks open while the reply is still being written** — the ids are
|
|
stable across every swap and across the final one, and opening a block
|
|
stops the thread chasing the bottom until you scroll back down
|
|
- [x] Per-reply metrics — tokens, context used as a percentage, tokens/second,
|
|
live while streaming and kept afterwards. Estimated with a `~` when the
|
|
endpoint reports no usage. Two chips: what the reply **cost** and what the
|
|
conversation now **occupies**, each labelled, both moving between one
|
|
usage block and the next rather than once a round
|
|
- [x] Compaction — a button, and automatically at a configurable percentage of
|
|
the model's context. Summarised turns are kept and collapsed, not deleted
|
|
- [x] Temporary chats — never listed, swept after a day, with a Keep button
|
|
- [x] An admin-only request inspector beside the thread
|
|
- [x] **Canvas** — a third side panel holding open files, in tabs. Project files
|
|
over SFTP in an agent chat; notes, skills, knowledge documents, this
|
|
chat's text attachments and its own scratch document everywhere. Read with
|
|
syntax highlighting, edited in a plain textarea, saved with a conflict
|
|
check. Files the model touches open themselves, without taking the screen
|
|
|
|
### Tools
|
|
- [x] **Tool calling** — one reply is a bounded loop of requests, not one
|
|
request. Text produced before a call is kept
|
|
- [x] **Web search** as the first tool: DuckDuckGo (no setup), SearXNG or
|
|
Firecrawl, chosen in the admin area
|
|
- [x] Only offered to models flagged `tools`, because an endpoint without
|
|
support rejects the whole request rather than ignoring the array
|
|
- [x] Sources stay in the transcript; results are **not** replayed as context on
|
|
the next turn, for the same reasons reasoning is not
|
|
- [x] A round's calls run together, and the reply says which tool is running —
|
|
a remote tool taking seconds with nothing streaming looks like a hang
|
|
- [x] **A reply can stop and ask you something** — one or more questions on one
|
|
card, with answers to pick from and a box to write your own, answered
|
|
together. The same mechanism carries command approvals
|
|
- [x] **Custom HTTP tools** — an administrator describes one call: a JSON Schema,
|
|
a URL template, headers, an encrypted secret and how to read the answer.
|
|
Arguments may fill a hole but never move the target: the scheme and host
|
|
are literal, values are escaped for where they land, and the origin is
|
|
pinned afterwards
|
|
- [x] **MCP servers** over streamable HTTP — a hand-written client, so that
|
|
`check_url` runs on every hop rather than being bypassed by somebody
|
|
else's transport. Tools are discovered and cached by a button, namespaced
|
|
per server, and a server's own descriptions are bounded before they reach
|
|
a model as instructions
|
|
- [x] Both gated like the built-ins — a model capability, a permission — and
|
|
restrictable to groups, with guidance of their own on `/admin/prompts`
|
|
- [x] Local MCP over stdio is deliberately absent: spawning a subprocess would
|
|
run on this machine, which nothing here does
|
|
|
|
### Image generation
|
|
- [x] **Draws on a ComfyUI you are running**, as a tool the model chooses to
|
|
call and as an `/image` command that makes it call one. Never on this
|
|
machine, the same rule agent chats follow
|
|
- [x] **Multiple workflow templates** — a name, a description and a ComfyUI API
|
|
export with `{{prompt}}` and ten other placeholders where the values go.
|
|
The model picks between them by their descriptions, and by checkpoint,
|
|
falling back to the chat's usual and then the instance default when it
|
|
names neither
|
|
- [x] Model may set prompt, negative, seed, steps, cfg, width, height, sampler,
|
|
scheduler, denoise, checkpoint and template; **only the prompt is
|
|
required** and everything else has a default
|
|
- [x] **The result is checked before you see it** — optionally, a vision model
|
|
is shown the picture and the request and says keep or retry, up to a
|
|
configurable number of attempts. Only clearly wrong images are retried;
|
|
the last attempt is kept whatever it says, so a request always produces
|
|
something
|
|
- [x] **Preserve VRAM** — opt-in, for a machine that cannot hold both at once:
|
|
unload the chat's own language model, generate, free ComfyUI, and let the
|
|
next request load the model back. Per connection, so a box on the network
|
|
is never touched
|
|
- [x] Instance-wide extra instructions, injected into the harness beside the
|
|
tool's own guidance
|
|
- [x] **Failures say what actually happened** — out of memory, cancelled, or a
|
|
node that raised, read out of ComfyUI's own record within a second rather
|
|
than waiting out the timeout. A memory failure tells the model to retry at
|
|
a named smaller size or a lighter checkpoint; a cancelled one tells it not
|
|
to start again
|
|
- [x] Every parameter described by what it does to the picture and when to move
|
|
it, because a model given "cfg: default 8" sends the prompt alone.
|
|
`docs/image-generation-instructions.md` is a longer set to paste into the
|
|
admin instructions box
|
|
|
|
### Agent chats
|
|
- [x] A chat is a **Chat** or an **Agent**, chosen when it starts and fixed
|
|
thereafter — a transcript whose earlier turns ran somewhere else is not
|
|
one conversation. Knowledge, memories and skills are shared across both
|
|
- [x] **Nothing runs on the LLeMbas host.** Commands go to a machine reached
|
|
over SSH, so containment is somebody's considered choice of host — a
|
|
container built for the job — rather than a sandbox built here. A local
|
|
one was designed in detail and dropped; see CLAUDE.md for why
|
|
- [x] **SSH connections are user-owned**, like notes. An administrator decides
|
|
only whether the feature exists at all
|
|
- [x] Trust on first use, made explicit: adding a host does not connect to it,
|
|
**Check** shows its fingerprint with nothing sent, and only accepting
|
|
pins it. A host that later answers with a different key is refused
|
|
- [x] Four modes as a table over what each tool does to the world —
|
|
**Manual** asks about everything, **Edit** writes freely but asks before
|
|
commands, **Auto** asks about nothing, **Plan** reads freely and changes
|
|
nothing. Switchable at any time; read once per reply
|
|
- [x] Enforced in the generation loop, not in the prompt: a rule a model is
|
|
merely told is one a poisoned file can argue with
|
|
- [x] A deny list beats **Auto** for any command it can match; an allow list
|
|
cannot be matched at all by a command containing anything that joins two
|
|
commands together. A deny pattern cannot either — so in Auto a compound
|
|
line runs, which is the trade for Auto not asking about `cd build && make`.
|
|
See CLAUDE.md; matching each segment would restore both and is not built
|
|
- [x] **The terminal and the canvas open before the chat exists** — on the
|
|
new-chat screen, against the connection and directory being chosen there,
|
|
and both re-point when that changes. The shell you opened and the files
|
|
you left open are adopted into the chat when you send the first prompt
|
|
- [x] **Background jobs are visible** — a chip in the composer row counting what
|
|
is still running, and a panel with each job's command, state, log tail,
|
|
how long it took and a Stop button. The dot is coloured by outcome rather
|
|
than by status, since `done` covers exit 0 and exit 2 alike. Survives a
|
|
restart, because the job does
|
|
- [x] `shell_run`, `file_read`, `file_write`, `file_list` — files over SFTP,
|
|
never through a shell, because the SSH exec protocol has no argv form
|
|
- [x] **Plan mode ends with a plan** you can carry out with one button, which
|
|
switches to Edit and sends it back quoted rather than as an instruction
|
|
- [x] Per-reply budgets on steps, wall clock and output, with time spent
|
|
waiting for you subtracted
|
|
- [x] **A terminal panel** beside the chat, holding a real shell on that chat's
|
|
own connection. The modes govern the model; what a person types is theirs,
|
|
since they hold the credential and could open the same shell with an ssh
|
|
client. The model cannot see the panel — sending it output is a button
|
|
- [x] The shell outlives the panel and the page: closing it leaves a build
|
|
running, and coming back reattaches with the scrollback. An idle timeout
|
|
is what eventually ends one, and so does deleting the chat, or disabling,
|
|
moving or deleting the connection
|
|
- [x] **The panel is resizable**, dragged from its edge or nudged with the
|
|
arrow keys, and the width follows you to another browser
|
|
- [x] **It knows where one command ends and the next begins** — bash and zsh
|
|
are given the markers VS Code and WezTerm use, so *Copy* and *Send* mean
|
|
one command and its output rather than the last forty rows of the screen.
|
|
An **Auto** toggle collects each one into the next message. Any other
|
|
shell starts exactly as it did before, the buttons fall back to the
|
|
screen and say so, and Auto is disabled rather than degraded
|
|
- [x] **The project directory is listed for the model** — one read-only
|
|
command, `git ls-files` where that works so `.gitignore` is honoured for
|
|
free, budgeted so a big directory becomes a count rather than a thousand
|
|
filenames on every request
|
|
- [x] **A directory is chosen by browsing it** over SFTP, not by typing a path
|
|
into an unlabelled box
|
|
- [x] The approval mode is chosen **before** the first message, beside the
|
|
message box rather than in the header
|
|
|
|
### The library
|
|
- [x] **Knowledge bases** — documents, images and saved web pages, grouped into
|
|
named collections and ingested through the same pipeline as chat
|
|
attachments, searched with SQLite FTS5
|
|
- [x] A chat can be pointed at particular bases, so "answer from the contracts
|
|
folder" is a different question from "answer from everything I have"
|
|
- [x] **Notes** — longer things the model writes down and searches later;
|
|
editable by hand, because they are yours
|
|
- [x] **Memory** — short facts, injected on every turn to a budget rather than
|
|
searched, and managed in your settings
|
|
- [x] **Skills** — saved procedures. Only the name and description are injected;
|
|
the body is fetched when the model decides it applies
|
|
- [x] A model may write and revise its own notes, memories and skills. Every
|
|
skill revision is kept, attributed and revertible — the safety story is a
|
|
record and a way back, not a gate
|
|
- [x] **Sharing** — a knowledge base, a note or a skill can be shared with a
|
|
group or with named people, read-only. One visibility rule, and
|
|
administrators do not bypass it. Documents are shared through their base
|
|
- [x] **The harness** — an operational prompt assembled from what a model
|
|
actually has, so the tools get used rather than ignored
|
|
- [x] Attach menu: file, image, a web page fetched on the spot, or a document
|
|
from the library
|
|
- [x] **`@` to name one** — the library everywhere, and files in the project
|
|
directory in an agent chat. The reference stays in the sentence and the
|
|
contents come along, with the path and the machine, so the model knows
|
|
exactly which file it was handed
|
|
|
|
### Scheduling
|
|
- [x] **Schedules** — work that runs because time passed rather than because
|
|
somebody asked just now. Fire once or repeat; a fixed number of runs or
|
|
until stopped; a timer ("every ten minutes") or a calendar ("every Monday
|
|
at 3PM"), and the two compose into "every other Monday"
|
|
- [x] **Wall-clock and elapsed time are kept apart**, because they mean
|
|
different things: a calendar time stays 15:00 across a daylight-saving
|
|
change, while a six-hourly timer stays six hours. A time that does not
|
|
exist on a spring-forward day fires at the first minute that does
|
|
- [x] **Per-user timezone**, so "every Monday" means the reader's Monday. The
|
|
harness tells them their own time now, not the server's
|
|
- [x] **Scheduled** — one chat per task, replied into each time it comes round.
|
|
No composer: run it now, pause it, edit it, remove it
|
|
- [x] A missed run **catches up once** and then resumes. A week of downtime owes
|
|
one report, not a hundred and sixty-eight
|
|
- [x] Claim before firing, so a run that fails moves the schedule on rather than
|
|
retrying every tick for ever; and "Run now" deliberately does *not* consume
|
|
the run it was testing
|
|
- [x] **Say it in your own words** — a model turns "every Monday morning, check
|
|
the build" into a recurrence and an instruction that reads on its own,
|
|
and shows it back for approval before anything is saved. Anything it
|
|
cannot work out lands in the same form, filled in as far as it got
|
|
- [x] A scheduled run knows nobody is watching: `ask_user` is **withdrawn**, not
|
|
merely discouraged, because a question with no one to answer it holds the
|
|
reply until it times out
|
|
|
|
### Messages
|
|
- [x] **Messages** — one conversation per person that is meant to run for
|
|
years. It opens on the most recent turns and pages older ones in as you
|
|
scroll up
|
|
- [x] **Bounded in the request, unbounded on disk.** Only the latest chunk is
|
|
sent to the model; everything else stays exactly where it was written.
|
|
Nothing is folded into text and nothing is deleted
|
|
- [x] Anything scheduled can post here, and the schedules that do are listed
|
|
beside the conversation rather than two pages away
|
|
|
|
### Reports
|
|
- [x] **Reports** — a section of its own for finished work: an investigation
|
|
written up, an account of what an agent chat changed, whatever a schedule
|
|
leaves behind. Filed with `report_write`, searched with FTS5, read on its
|
|
own page
|
|
- [x] **Nothing here can be replied to**, and that is the section rather than a
|
|
restriction on it. No composer, no route that accepts a message, and
|
|
nothing on either page that renders the streaming shell — so there is
|
|
nothing that could start a generation
|
|
- [x] Its own family, permission and capability flag, so a model that keeps
|
|
notes need not file reports and a model that files reports need not have
|
|
a library at all
|
|
|
|
### Audio
|
|
- [x] **Dictation** — record in the composer, transcribed by any OpenAI-shaped
|
|
`/v1/audio/transcriptions` endpoint. The recording never touches disk
|
|
- [x] **Read aloud** — any `/v1/audio/speech` endpoint, with the voice list
|
|
discovered from the server where it offers one
|
|
- [x] Instance defaults in Admin, per-reader overrides in Settings — voice,
|
|
speed, dictation language, and whether replies play automatically
|
|
|
|
### Models and reasoning
|
|
- [x] OpenAI-compatible connections with encrypted keys and model discovery
|
|
- [x] **Reasoning display** — `reasoning_content` and inline `<think>` tags,
|
|
collapsed by default, labelled with how long it took, never replayed as
|
|
context
|
|
- [x] Model admin as a list plus a page per model; scales to hundreds
|
|
- [x] Ordering, pinning (a sidebar shortcut, *not* a reordering), instance
|
|
default, per-user default, images, capability flags
|
|
- [x] Custom model picker showing avatars, descriptions and capabilities
|
|
|
|
### Attachments
|
|
- [x] Drag, paste or pick images, PDFs and text files
|
|
- [x] Images downscaled and sent to vision models as content parts
|
|
- [x] PDF and text extracted at upload and placed in the prompt
|
|
- [x] Type decided by inspecting bytes, random names on disk, non-images served
|
|
as downloads with `nosniff`
|
|
- [x] No OCR: a scanned PDF says so rather than silently contributing nothing
|
|
|
|
### People
|
|
- [x] Accounts, argon2, revocable server-side sessions, self-service password
|
|
change
|
|
- [x] Users and groups with permissions that **union** rather than override
|
|
- [x] Model access restricted to chosen groups
|
|
- [x] Registration toggle, instance settings stored in the database
|
|
|
|
### Prompts
|
|
- [x] Three layers — instance, model, chat — with the most specific winning
|
|
**outright** rather than being concatenated
|
|
- [x] Every injected fragment editable at `/admin/prompts`: the tool guidance,
|
|
the memory and skill sections, the seam above the authored prompt, and the
|
|
request that names a chat
|
|
- [x] `{{variables}}` with a legend, values shown as they currently resolve, and
|
|
pass-through for anything that is not one
|
|
- [x] A preview of the whole assembled system message, including unsaved edits
|
|
- [x] Defaults in code and overrides in the database, so improving a default
|
|
still reaches an instance that never edited it
|
|
|
|
### Suggestions
|
|
- [x] Admin-managed cards on the new-chat screen; three seeded once at startup
|
|
|
|
### Interface
|
|
- [x] **`/` for commands** — compact, usage, mode, model, title, the panels,
|
|
the theme. Anything not in the table is sent as an ordinary message, and
|
|
`//` starts one with a literal slash
|
|
- [x] **Keyboard shortcuts** for the same jobs, listed beside the commands in
|
|
one table so `/help` cannot go stale
|
|
- [x] Mentions and recognised commands are marked as you type, and again in the
|
|
transcript, so you can see what a message will do before sending it
|
|
- [x] **Reasoning effort** per chat, with a per-model default. Sent as both
|
|
`reasoning_effort` and `chat_template_kwargs`, and only once chosen:
|
|
OpenAI and vLLM read the first, llama.cpp silently drops it and reads
|
|
only the second
|
|
- [x] **Installable** — manifest, generated PWA icons, a service worker for the
|
|
shell and a themed offline page. The worker deliberately never touches
|
|
`/api/`: a reply is an event stream and caching one breaks it
|
|
- [x] Two themes (`moria`, `shire`) from one set of design tokens
|
|
- [x] Every control sized from `--control-h`, so rows line up by construction
|
|
- [x] Toasts and dialogs of our own; no `window.confirm` anywhere, and
|
|
`data-prompt` for asking one line before a request goes out
|
|
- [x] **An approval card's command can be corrected** before it is allowed, and
|
|
the transcript says who wrote what ran
|
|
- [x] **Refusing can say why** — "Give reason" opens a box beside Don't, and what
|
|
you write goes back as the instruction rather than as a rejection, so the
|
|
model carries on from it instead of spending a round asking what you meant
|
|
- [x] Original SVG artwork generated from a single source
|
|
|
|
### Operations
|
|
- [x] Additive schema sync — new tables and columns applied at startup
|
|
- [x] `deploy/` — systemd unit and nginx templates, install and update scripts
|
|
|
|
---
|
|
|
|
## Not built yet
|
|
|
|
In the order they are likely to be worth doing.
|
|
|
|
### Smaller things
|
|
- **OCR** for scanned PDFs
|
|
- **Conversation branching** — `Message.parent_id` exists unused; needs a UI for
|
|
choosing between versions, which is why rewind truncates for now
|
|
- **Chat export** (Markdown, JSON)
|
|
- **Semantic search** in the library — the retrieval service is one call, so an
|
|
embedding backend can go behind it without touching the tools or the UI
|
|
- **Archived chats** — the column exists, nothing surfaces it
|
|
- **Per-user quotas**
|
|
|
|
---
|
|
|
|
## Known limits
|
|
|
|
Worth knowing before they surprise someone.
|
|
|
|
**One worker.** The generation registry and the stop mechanism are in-process.
|
|
Running several workers needs that state in the database or a broker, because
|
|
the request following a reply would not necessarily land in the process writing
|
|
it.
|
|
|
|
The schedule ticker is now the strongest reason this is not merely a
|
|
convenience. It is in-process like the rest, so **two workers means two tickers
|
|
and every schedule firing twice**. The claim that prevents a double-fire is a
|
|
Python lock plus a write committed in the same transaction, not `SELECT ... FOR
|
|
UPDATE`, which SQLite does not have. Scheduling also makes downtime visible in a
|
|
way nothing else here does: a dropped reply is one somebody watched fail, while
|
|
a missed run is one nobody saw at all — which is what the catch-up in the sweep
|
|
is for, and why it lives there rather than in a startup hook (a suspended host
|
|
or a long stall reproduces it with no restart to hang one on).
|
|
|
|
**A restart abandons replies in flight.** Shutdown cancels them and keeps what
|
|
each had. There is no resume.
|
|
|
|
**Schema changes are additive only.** New tables and columns apply themselves;
|
|
renames, drops and retypes are manual against the SQLite file. `MANUAL_STEPS`
|
|
in `db/migrations.py` is where such a step gets recorded.
|
|
|
|
**Attachments live on disk, unreferenced files are swept at startup.** No
|
|
deduplication, no size quota.
|
|
|
|
**Unread is polled every 10 seconds.** A push channel would be more responsive
|
|
but means an always-on connection per tab for the sake of a green dot.
|
|
|
|
**Installing needs HTTPS or localhost.** Service workers are unavailable over
|
|
plain HTTP, so a LAN install without TLS is a normal browser tab. The
|
|
microphone is unavailable for the same reason.
|
|
|
|
**Tool calling needs a model that supports it.** The `tools` flag is an
|
|
administrator's assertion, not something endpoints reliably advertise. Set it on
|
|
a model that cannot, and its replies fail rather than degrade.
|
|
|
|
**Library search is keyword, not semantic.** FTS5 ranks well and needs no
|
|
dependency or embedding endpoint, but "how do I get paid" will not find a
|
|
document that says "invoicing".
|
|
|
|
**A model can write its own skills, and they take effect at once.** Marked as
|
|
model-authored and fully revertible, but a model that has just read a hostile
|
|
page could save a skill that outlives the conversation. The mitigation is that
|
|
it is visible and undoable, not that it was prevented.
|
|
|
|
---
|
|
|
|
## Deliberate decisions
|
|
|
|
Recorded because each looks like an oversight until you know the reason.
|
|
|
|
- **No JavaScript build step.** Browser libraries are hash-pinned and committed.
|
|
A self-hosted tool should work offline and not report page views to a CDN.
|
|
- **Permissions union, never deny.** With denies, "why can this user not do X"
|
|
cannot be answered without simulating every group.
|
|
- **System prompts replace, never stack.** Two layers that disagree give the
|
|
model contradictory instructions and nobody can tell which is losing.
|
|
- **Rewind truncates, does not branch.** Branching needs a UI for choosing
|
|
between versions; "go back and try again from here" is what was asked for.
|
|
- **Pinning is a shortcut, not an ordering.** A picker whose order silently
|
|
differs from the admin screen is confusing.
|
|
- **Images only reach models marked `vision`.** Not graceful degradation: most
|
|
endpoints reject the entire request rather than ignoring an image part. Tools
|
|
are gated the same way, for the same reason.
|
|
- **Sharing grants reading, never writing.** Two people editing one note with no
|
|
history and no merge is worse than the inconvenience of copying it.
|
|
- **Memory is never shareable.** A record about a person is not content to hand
|
|
round.
|
|
- **Knowledge attached to a message is copied, not referenced.** History must not
|
|
change under a conversation because a document was edited later.
|
|
- **The harness is prepended to the authored prompt, not a fourth layer.** It
|
|
describes the machinery; the authored layers describe the behaviour. Only one
|
|
authored layer still wins.
|
|
- **Tool results are not replayed.** Like reasoning: the answer already contains
|
|
what the model made of them, and replaying stale results into every later
|
|
request wastes the window and sends small models into search loops.
|
|
- **The service worker caches the shell, never a page with a user in it.** A
|
|
cached conversation would be a snapshot that silently went stale, belonging to
|
|
whoever was signed in last.
|
|
- **Markdown rendered server-side.** One code path produces the streamed and
|
|
the stored view, so they cannot disagree.
|
|
- **This repository is public.** Deployment hostnames, ports and paths stay out
|
|
of it; `deploy/` is templates, and the real values live in private notes.
|