ATProto-based AI Assistant Chat interface.

26 files

pouriade.com · Open the Add a key form from a button · 1d ago

admin-plugins.md

Add support for per-provider model capability defaults.

admin-settings.md

pnpm preview builds the web app and runs the production build on this machine, at http://127.0.0.1:3000, where before production refused any PUBLIC_URL that wasn't HTTPS. A loopback PUBLIC_URL now passes in production, and needs no OAUTH_PRIVATE_KEYS, since sign-in there uses the loopback client, as in development. Any other plain-HTTP URL is still refused. pnpm start stays the command a deployment runs, serving the build it was given. The README, the foundation spec's scripts, and the auth and admin settings specs describe it, with a test.

Port the admin area from design-reference. Users is a card to add a person over those waiting to sign in, then a search over a list of accounts, each with its initial, its DID, storage, and last activity, its roles as chips with a picker to add one, and its access at the end, where Suspend asks for a reason first. Roles and plugins are lists whose rows open their pages, which link back above their titles, a plugin's numbered in load order with its status and arrows to move it. A role's page holds its members, then its details with hosts and domains in a mono field. Access picks a registration mode from choices, with invite roles as chips that toggle. Models picks the default by a click anywhere on its row. A plugin's page holds its settings, a list of its provider's models, and a card to tick or type more. A model's capabilities are switches. Removing a role, plugin, or model, and revoking a key, confirm in place, and each sits in a red card. An issued key shows once in a green note with Copy. Cron shows the last run with a badge and the crontab line to copy. General, Turns, and Sync choose their cards per route, and the settings schemas gain clearer titles, descriptions, and units, which SchemaFields shows after a number.

Add site-config export / import via CLI.

A file in a sent message shows as the chip it was in the composer, with its icon, name, and kind and size, as "PDF · 1.2 MB", rather than a bare link holding its name. The chip moves to src/shared/ui as FileChip, which the composer and the message share. The whole chip is a link: a PDF opens in a new tab in the browser's own viewer, ending in an arrow out, and any other file downloads under its name, ending in a download arrow. Files side by side share a row that wraps toward the message's edge. The blob routes, the owner's and the shared one, serve a PDF inline and take application/pdf as a type, so a spaces user's PDF reaches the browser as one. The attachments, web UI, and styling specs say so.

pnpm setup-env creates .env from .env.example and fills in fresh OAUTH_PRIVATE_KEYS and SECRET_KEY, so local setup is one step instead of copying secrets by hand. It is pnpm keys --write, which never replaces a secret already set, since a new SECRET_KEY can't decrypt stored API keys; plain pnpm keys still prints a pair.

browser-store.md

The notice that another tab holds the chats is a card in the middle of the blurred chat panel, as Jump to's layer blurs it, rather than a line of unstyled text, and so is the one for a store that failed to open. The page behind can't be reached by pointer or keyboard, the card's button takes the keyboard, and the card stays up with its button busy while a retry waits. BusyBanner becomes StoreUnavailable, which wraps the page, and the error page's round icon mark becomes IconMark, shared by both.

chat-storage.md

Upgrade spaces alpha to 20261022. Verify commit and record MACs against #atproto_kem, falling back for accounts without one. New credential exchange and scheme.

Bump the chat index only after replying. Wait before claiming a synced turn.

Merge web-rebuild: the web app on TanStack Start. Port main's no-models composer block, role and model summary pages, API keys and Cron pages into its feature folders

encrypted-conversations.md

Add admin and encryption specs to the repo.

The app can be installed from Chrome, Edge, and Android, or added to an iPhone's home screen, and opens in its own window. The server builds /manifest.webmanifest from the admin area's name, the icons are drawn from logo.svg on the sign-in page's dark tile by pnpm --filter @scn-chat/web icons, and theme-color tags follow the scheme fixed on the device. A hand-written service worker, stamped per build by a Vite plugin, keeps only the hashed /assets files and an offline page, leaves the API, sign-in, and XRPC to the browser, and drops the previous build's cache, so no chat content is cached (ADR 0006). The spec is specs/installable-app.md.

When the app runs on this machine and its port is taken, the server moves to the next free one, trying up to twenty, and PUBLIC_URL with it, since the OAuth redirect and the app's links name that address, and logs a warning saying so. It moves only when PUBLIC_URL is loopback on that same port, so a deployment, or a loopback URL that names another port, keeps its port and fails to start as before, since a reverse proxy points at it. A port counts as taken when it is at every address or at 127.0.0.1 or ::1 alone, since macOS lets a listener on every address share a port with one on 127.0.0.1, which then still gets the requests for http://127.0.0.1:3000. The tunnel picks the free port itself and points both ssh and the server at it. The foundation spec and .env.example describe it, and the tests cover the probe and when the environment moves.

installable-app.md

Add a PNG favicon and the manifest's lang

The conversation:created and conversation:deleted plugin hooks run once for each conversation created or deleted, whichever client made the change, where before only the app's own routes ran them. fireChatHooks, wired in server.ts, runs them from the in-process event bus. ChatService announces the conversations the app creates and deletes, through a listener in place of its onWrite callback. Sync announces one another client created when an index sync finds a new conversationRef, whose op has no previous CID, and one another client deleted through the engine's new conversationDeleted, which the deleted index entry, the missing space, and notifySpaceDeleted all go through. RecentWrites remembers the spaces the server deleted for ten minutes, so sync noticing the server's own deletion doesn't announce it again. The first index sync after sign-in, and any while the index is empty, announces nothing. The routes no longer wait for the hooks before answering, and open tabs now hear about deletions made through the app too. The plugins spec and guide describe it, with tests and an acceptance criterion.

Add support for per-provider model capability defaults.

The app can be installed from Chrome, Edge, and Android, or added to an iPhone's home screen, and opens in its own window. The server builds /manifest.webmanifest from the admin area's name, the icons are drawn from logo.svg on the sign-in page's dark tile by pnpm --filter @scn-chat/web icons, and theme-color tags follow the scheme fixed on the device. A hand-written service worker, stamped per build by a Vite plugin, keeps only the hashed /assets files and an offline page, leaves the API, sign-in, and XRPC to the browser, and drops the previous build's cache, so no chat content is cached (ADR 0006). The spec is specs/installable-app.md.

scn-member-registry.md

Merge web-rebuild: the web app on TanStack Start. Port main's no-models composer block, role and model summary pages, API keys and Cron pages into its feature folders

The chat list and its rows do less work, from an audit against React performance practice. Opening a search hides the chat list inside React's Activity rather than unmounting it, so closing the search brings the chats back as they were rather than mounting every row again. A chat row no longer holds three mutations: renaming and tagging are an EditChat card and deleting a DeleteChat card, each holding its own, so an idle row holds none, and cancelling a failed change clears its error with the card. Picking a tag keeps the rows shown until its chats arrive, rather than a skeleton between. The month headings of older chats come from two formatters made once, rather than one made for each chat on every change to the list. A reply's sources and a search's results take the fold's ref apart, so React Compiler compiles them rather than silently leaving them out. The conversation's rename, instructions, and sync call their mutations' own functions, so the header no longer renders with every state either passes through, and its jump outline is built only while the jump stack is open. The search spec says the list stays mounted, and the list test checks it is hidden.

Upgrade spaces alpha to 20261022. Verify commit and record MACs against #atproto_kem, falling back for accounts without one. New credential exchange and scheme.

Add site-config export / import via CLI.

Guard the design system's scales in the theme test

A reply streams at an even pace, a word at a time, or a character at a time for Chinese and Japanese, where before it arrived in whatever bursts the provider sent. The turn's streamText uses the AI SDK's smoothStream with a chunking pattern of our own, since the SDK's word chunking waits for a space and would hold back Chinese and Japanese until a line ended. It waits 10 ms after each piece of text and reasoning alike, which caps a reply at about 100 words a second, so a faster model's record is written once smoothing catches up, within the turn's timeout. OpenAI-compatible models now show reasoning a server leaves in the reply inside <think> tags, such as llama.cpp with --reasoning-format none, as reasoning rather than as part of the answer, through the AI SDK's extractReasoningMiddleware, so that plugin now depends on the ai package. Its new startWithReasoning option is for models such as DeepSeek R1 whose template opens the tag in the prompt, so a reply has only the closing tag. The titles plugin refuses output that stopped at its output limit, such as reasoning that never reached its closing tag. The chat turns, providers, and titles specs describe it, along with the reasoning middleware dropping a reply's last characters when they could start a tag, which is a bug in the AI SDK, and docs/plugins.md says when a provider needs the ai package. Tests cover the smoothing, reasoning in think tags with and without the opening tag, whether streamed or not, and the cut-off title.

A pending reply is drawn by one module, PendingReply.tsx: its waiting or live header, its stream, and the lines about a wait, a busy provider, or a lost stream, until its finished record replaces it. MessageView uses it while a record is pending, and it follows the conversation the FollowedConversation context names, which ConversationView provides, so MessageView and BranchView no longer take pending and live slots and BranchRow no longer checks the status. The stream's part views get the pending record rather than a made-up one, and the model's name comes from MessageView alone. LiveAuthor.tsx, ReplyStream.tsx, and StreamingReply.tsx are gone. A conversation test streams a reply, then has its record arrive, and checks the time it thought carries over and its text shows once.

Pass error messages from search engines back to the LLM, rather than just error codes.

Open the Add a key form from a button

README.md

Specs #

Each file here describes one feature of SCN Chat: what it does, why it exists, how it is built, what it deliberately leaves out, and how to tell it works. A spec is written and agreed on before the feature is built, and kept current as the feature changes.

Specs are the source of truth for behavior. When code and spec disagree, one of them is wrong, and the fix is to bring them back in line rather than let them drift. A spec should be detailed enough that someone, or an LLM, could rebuild the feature from it plus the project's CLAUDE.md.

These files are all AI generated and maintained.

The overview at the end of this file lists every spec and whether it is active, planned, or done.

Sections #

Summary: what the feature does, for someone meeting it for the first time.
Motivation: the problem it solves, with enough context to make good judgment calls.
Design: the technical approach, data shapes, and where the code lives.
Scope Boundaries: what the feature does not do.
Edge Cases and Decisions: a running log of non-obvious choices.
Acceptance Criteria: checks that each become at least one test.
Files: the code that implements the feature, used to spot specs that have fallen behind the code.

Overview of Feature Specs #

Active #

[[site-config]]: the whole admin configuration exported and applied as one JSON document, through a CLI on the server, for deployment tools like Ansible.
[[extending]]: the web app made easy to change in a fork, with tables of part and tool views, tool status and steps, message actions as a list with Copy, a Markdown seam with code block copy, smaller components, and a guide in docs/extending.md. Phase 3 of the web rebuild, partly built.
[[installable-app]]: the web app installable as an app, with a manifest named from the admin area, icons drawn from the logo, and a service worker that keeps only the build and shows an offline page.

Planned #

[[encrypted-conversations]]

Completed #

Phase 1, initial build-out, implemented and tested against real spaces PDSs:

[[foundation]]
[[plugins]]
[[auth]]
[[chat-storage]]
[[providers]]
[[chat-turns]]
[[attachments]]
[[titles]]
[[sharing]]
[[browser-store]]

After the initial build-out:

[[search]]
[[web-search]]
[[admin]]
[[admin-plugins]]
[[admin-settings]]
[[api-keys]]
[[cron]]
[[scn-member-registry]]
[[tool-views]]: tool calls shown as what they did, through a table of tool views with one derived status, starting with web search and web fetch. Split out of [[extending]].

Phase 1 of the web rebuild:

[[web-ui]]: rebuilding the web app on TanStack Start inside Hono, at parity with its acceptance criteria.

Phase 2 of the web rebuild:

[[styling]]: Tailwind over a theme of design tokens, a light and dark picker, code highlighting, and the design from the design-reference branch with its behavior, ported onto main.