@ykurilov/agent-chat-storage-sqlite 0.0.0-stage → 0.55.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yury Kurilov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @ykurilov/agent-chat-storage-sqlite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Хранилище чатов с агентом на SQLite (Drizzle и `better-sqlite3`).
+
+```ts
+import { createSqliteChatStorage } from "@ykurilov/agent-chat-storage-sqlite";
+
+const storage = createSqliteChatStorage({ filePath: "chat.sqlite" });
+// …
+storage.close(); // при остановке сервера
+```
+
+Таблицы создаются и обновляются сами при открытии базы (в том числе колонка `title` для списка чатов: названия старых чатов заполняются по их первому сообщению). Последний выбор модели человека (для новых чатов) лежит в таблице `user_model_choices`. Сообщения не переписываются
+задним числом: меняется только ответ, который ещё пишется.
+
+Состояние лимитов расходов лежит в таблице `spending_limit_states` (запись по версии: из двух одновременных записей с одной версией проходит одна; миграция применяется сама).
+
+Идущий ответ отмечается «жив» (колонка `alive_at`, миграция применяется сама), расход помечается «примерно» (колонка `estimated`). SQLite живёт на одной машине с сервером; несколько копий на одной базе и одном компьютере работают так же, как на PostgreSQL.
+
+## Где лежат данные SDK
+
+SDK держит свои таблицы (`chats`, `messages`, `user_model_choices`, `spending_limit_states` и другие) и свой журнал миграций `__agent_chat_migrations` в одном файле. Дайте ему отдельный файл: свои таблицы приложения туда не кладите.
+
+До версии 0.32 журнал SDK лежал в общей таблице drizzle `__drizzle_migrations`. Если приложение вело в том же файле свои миграции drizzle, SDK мог пропустить свои. При первом открытии новой версией записи SDK сами копируются в `__agent_chat_migrations`, уже применённые миграции не повторяются. Пропущенные миграции SDK применяются, даже если они в середине, а более поздние уже прошли: SDK сверяет каждую миграцию по своему журналу, а не только последнюю. Общая таблица остаётся как была.
+
+При открытии, до миграций, SDK проверяет файл. Если в нём есть `chats` или `messages`, а журнал миграций SDK их не знает, значит таблицы чужие. Тогда `createSqliteChatStorage` бросает `ForeignChatTablesError` («дайте SDK отдельный файл»), закрывает файл и ничего в нём не меняет. Таблицы не переименованы, чтобы не ломать уже работающие базы. В PostgreSQL SDK живёт в своей схеме `agent_chat`, там чужим таблицам места нет.
+
+`better-sqlite3` приходит с готовыми сборками (macOS, Windows, Linux, в том числе Alpine): собирать ничего не нужно.
+pnpm 10 напишет «Ignored build scripts» — это можно не трогать. Разрешать сборку
+(`onlyBuiltDependencies: [better-sqlite3]` в `pnpm-workspace.yaml`) нужно, только если у вашей платформы готовой сборки нет.
+
+Подключение целиком: [docs/getting-started.md](https://github.com/ykurilov/agent-chat-sdk/blob/main/docs/getting-started.md).
+
+Журнал изменений и что делать при обновлении: [CHANGELOG.md](./CHANGELOG.md). Все пакеты SDK выходят вместе и с одной версией; обновление — `pnpm update "@ykurilov/agent-chat-*" --latest`.