local-agent-chat 0.1.0__tar.gz

local_agent_chat-0.1.0/.env.example

@@ -0,0 +1,28 @@
+APP_PORT=8765
+# APP_HOST=127.0.0.1
+# APP_ROOT_PATH=/user/name/vscode/proxy/8765
+APP_DATA_DIR=.local-agent-chat
+MODEL_PROFILES_FILE=models.yaml
+CHAINLIT_AUTH_SECRET=replace-with-a-random-secret-at-least-32-characters
+OPENAI_BASE_URL=https://openrouter.ai/api/v1
+OPENAI_API_KEY=replace-with-your-openrouter-api-key
+
+# Additional attempts after the first LLM HTTP request (0-10); 0 disables retries.
+LLM_MAX_RETRIES=3
+# Timeout for one LLM HTTP request.
+LLM_REQUEST_TIMEOUT_SECONDS=60
+# Maximum pause between streamed chunks; a stream is terminal after its first chunk.
+LLM_STREAM_CHUNK_TIMEOUT_SECONDS=120
+# Additional model-handler attempts after a zero-chunk stream timeout (0-10).
+LLM_STREAM_RETRIES=1
+# Total timeout for one auxiliary Chat-title LLM call.
+LLM_AUXILIARY_TIMEOUT_SECONDS=30
+
+# ReAct context window, compaction, output and per-Turn inference budget.
+# Keep the context budget within the actual window of the configured model.
+AGENT_CONTEXT_TOKENS=16000
+AGENT_SUMMARY_TRIGGER_TOKENS=10000
+AGENT_KEEP_TOKENS=3000
+AGENT_SUMMARY_TOKENS=1000
+AGENT_MAX_OUTPUT_TOKENS=2000
+AGENT_MAX_MODEL_CALLS=12

local_agent_chat-0.1.0/CONTEXT.md

@@ -0,0 +1,45 @@
+# LocalChat
+
+Локальный чат-интерфейс для продолжительной работы пользователя с агентом в среде JupyterHub.
+
+## Language
+
+**Chat**:
+Продолжаемый диалог пользователя с агентом, имеющий собственную историю и память.
+_Avoid_: Session, conversation
+
+**Turn**:
+Один пользовательский запрос и связанный с ним ответ агента.
+_Avoid_: Message pair, interaction
+
+**Agent**:
+Участник чата, который отвечает пользователю, рассуждает и применяет доступные ему инструменты.
+_Avoid_: Bot, assistant
+
+**Sandbox**:
+Принадлежащее одному Chat хранилище загруженных файлов, которые Agent может читать. Revision восстанавливает файлы, соответствующие изменяемому запросу.
+_Avoid_: Workspace, project directory
+
+**Uploaded File**:
+Файл, явно переданный пользователем в чат и доступный агенту внутри Sandbox.
+_Avoid_: Attachment, workspace file
+
+**Chat History**:
+Сохранённые чаты, которые пользователь может вновь открыть после перезапуска приложения.
+_Avoid_: Logs, transcript archive
+
+**Agent Memory**:
+Контекст конкретного Chat: недавние сообщения и сводка более раннего диалога, необходимые Agent для продолжения работы.
+_Avoid_: Chat History, context
+
+**Model Profile**:
+Выбранная при создании Chat конфигурация модели, не содержащая секретов провайдера. Пока профиль доступен, он неизменяем; удалённый профиль при возобновлении Chat заменяется доступным fallback.
+_Avoid_: Provider, model settings
+
+**Revision**:
+Замена пользовательского запроса, после которой последующие Turn удаляются, Agent Memory, Uploaded Files и служебные артефакты возвращаются к состоянию перед изменяемым Turn, а Agent заново выполняет изменённый запрос.
+_Avoid_: Edit, branch
+
+**Local User**:
+Единственный пользователь экземпляра приложения, распознаваемый автоматически без экрана входа.
+_Avoid_: Anonymous user, account

local_agent_chat-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+## Локальный запуск
+
+```bash
+python -m pip install -e '.[test]' build twine
+localchat init --config-dir . --data-dir .local-agent-chat
+localchat run --config-dir .
+```
+
+Не используйте реальные секреты в тестах. Проверяйте запрет выхода из песочницы на файлах, созданных через `tmp_path`; тест не должен читать настоящие системные или пользовательские файлы.
+
+## Перед PR
+
+```bash
+pytest -q
+ruff check .
+ruff format --check .
+python -m compileall -q local_agent_chat
+bash -n scripts/run.sh
+python -m build
+python -m twine check dist/*
+python scripts/check_distribution.py dist/*.whl
+```
+
+- Добавьте тест для изменённого поведения.
+- Сохраняйте ровно четыре инструмента чтения песочницы: `ls`, `read_file`, `glob`, `grep`. Проверяйте суммаризацию, перезапуск и Revision через реальный `create_agent` с управляемой тестовой моделью.
+- Обновите README или `docs/architecture.md`, если изменился публичный flow.
+- Для нового архитектурного решения добавьте короткий ADR; термины меняйте через `CONTEXT.md`.
+- Не коммитьте `.env`, `models.yaml`, `.local-agent-chat/`, SQLite, скриншоты и логи.
+
+Карта файлов и точек настройки есть в README.
+
+Проверка дистрибутива создаёт чистое окружение вне checkout, устанавливает только runtime-зависимости и проверяет UI, загрузку файла, вызов инструмента, правку исторического запроса и восстановление после переустановки через локальную тестовую модель. Ресурсы UI находятся в `local_agent_chat/assets/`; CLI копирует их в отдельный временный каталог при запуске.

local_agent_chat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LocalChat contributors
+
+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.

local_agent_chat-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE README.md CONTRIBUTING.md SECURITY.md CONTEXT.md
+include .env.example models.example.yaml
+include scripts/run.sh scripts/check_distribution.py
+recursive-include tests *.py
+recursive-include docs *.md
+global-exclude *.pyc

local_agent_chat-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: local-agent-chat
+Version: 0.1.0
+Summary: Local chat UI with persistent history and a sandboxed ReAct agent
+Author: dev-sergeev
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dev-sergeev/local-agent-chat
+Project-URL: Documentation, https://github.com/dev-sergeev/local-agent-chat#readme
+Project-URL: Issues, https://github.com/dev-sergeev/local-agent-chat/issues
+Project-URL: Source, https://github.com/dev-sergeev/local-agent-chat
+Keywords: chat,llm,chainlit,react-agent,localchat
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chainlit<2.12,>=2.11
+Requires-Dist: langchain<2,>=1.2
+Requires-Dist: langchain-openai<2,>=1.6
+Requires-Dist: aiosqlite<1,>=0.20
+Requires-Dist: SQLAlchemy<3,>=2.0
+Requires-Dist: PyYAML<7,>=6
+Requires-Dist: python-dotenv<2,>=1
+Requires-Dist: platformdirs<5,>=4
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8; extra == "test"
+Requires-Dist: pytest-asyncio<2,>=1; extra == "test"
+Requires-Dist: python-socketio[client]<6,>=5.11; extra == "test"
+Requires-Dist: requests<3,>=2; extra == "test"
+Requires-Dist: ruff<1,>=0.13; extra == "test"
+Dynamic: license-file
+
+# LocalChat
+
+Однопользовательский Chainlit UI и обычный ReAct-агент на LangChain: модель вызывает инструменты чтения загруженных файлов и формирует ответ. История диалога, сводка контекста и файлы сохраняются локально.
+
+Агент предоставляет ровно четыре инструмента: `ls`, `read_file`, `glob`, `grep`. Их виртуальный `/` — файлы текущего чата. Выход в файловую систему хоста, другие чаты, запись файлов, shell и выполнение кода недоступны. Субагентов, планировщика, файловой выгрузки контекста и общей долговременной памяти нет.
+
+Редактирование исторического запроса удаляет его прежний ответ и последующее продолжение. Контекст вместе со сводкой и файлами восстанавливается перед изменяемым запросом, после чего агент отвечает заново. Ошибка или Stop восстанавливают прежнее состояние. Одинаковый текст правки сохраняет весь диалог.
+
+## Установка и первый запуск
+
+Требуются Python **3.12–3.13**, Linux (или WSL2) и OpenAI-compatible модель с tool calling. Пакет содержит UI, переводы и все ресурсы приложения; клонировать репозиторий для запуска не нужно. Windows без WSL не поддерживается из-за требований файловой песочницы. macOS пока не входит в проверяемые платформы.
+
+После публикации в PyPI установите приложение через [pipx](https://pipx.pypa.io/stable/installation/):
+
+```bash
+pipx install --python python3.12 local-agent-chat
+localchat init
+localchat run
+```
+
+`init` запросит модель, адрес API и ключ. Для OpenAI-compatible endpoint имя модели имеет вид `openai:<model-id>`, например `openai:deepseek/deepseek-v4-flash-0731` для OpenRouter. Ключ вводится без отображения в терминале; секрет сессии создаётся автоматически. `run` покажет адрес UI, по умолчанию **http://127.0.0.1:8765/**. Остановка — `Ctrl+C`; `--open-browser` открывает браузер автоматически.
+
+До первого релиза можно установить собранный wheel: `pipx install --python python3.12 ./dist/local_agent_chat-0.1.0-py3-none-any.whl`. Альтернатива pipx — `python3.12 -m venv .venv`, активация окружения и `python -m pip install local-agent-chat`.
+
+Для локального API без ключа:
+
+```bash
+localchat init --no-input --model openai:your-model \
+  --base-url http://127.0.0.1:8000/v1 --no-api-key
+```
+
+Для автоматической настройки с ключом передайте его в `OPENAI_API_KEY` и используйте те же аргументы без `--no-api-key`. `--api-key-env MY_PROVIDER_KEY` выбирает другое имя переменной; `--no-streaming` отключает потоковый ответ. Полная справка: `localchat init --help`, `localchat run --help`.
+
+## Настройки, данные и обновление
+
+На Linux по умолчанию используются:
+
+- `~/.config/localchat/.env` — параметры запуска и ключи, права нового файла `0600`.
+- `~/.config/localchat/models.yaml` — профили моделей; ключи здесь не хранятся.
+- `~/.local/share/localchat/` — SQLite, история и вложения.
+
+Учитываются `XDG_CONFIG_HOME` и `XDG_DATA_HOME`. `--config-dir PATH` или `LOCALCHAT_CONFIG_DIR` выбирает другой каталог конфигурации, `--data-dir PATH` — каталог данных. Относительные пути из `.env` разрешаются относительно каталога конфигурации. Приоритет: аргументы запуска, затем переменные окружения, затем `.env`, затем значения по умолчанию. `.env` читается как данные: shell-команды и подстановки `${...}` не выполняются.
+
+Повторный `init` не перезаписывает настройки. Для смены модели или ключа отредактируйте конфигурацию и перезапустите приложение. Обновление: `pipx upgrade local-agent-chat`; перед обновлением остановите процесс и сделайте резервную копию каталогов конфигурации и данных. Установка и переустановка пакета их не затрагивают. Два процесса не могут одновременно открыть один каталог данных.
+
+Если запуск сообщает об отсутствующей конфигурации, выполните `localchat init`. Для занятого порта используйте `localchat run --port 8766`. Ошибки модели отображаются в UI и терминале; используйте endpoint с поддержкой tool calling и бюджетом контекста, подходящим выбранной модели.
+
+## JupyterHub и существующая установка
+
+Для прокси задайте **полный публичный префикс**:
+
+```bash
+localchat run --port 8765 \
+  --root-path "${JUPYTERHUB_SERVICE_PREFIX%/}/vscode/proxy/8765"
+```
+
+Здесь переменную раскрывает shell перед вызовом команды. В `.env` нужно записать уже готовый путь, например `/user/alice/vscode/proxy/8765`. Неверный префикс может привести к белому экрану из-за неправильных адресов JavaScript. Проверяйте UI по публичному адресу прокси. Прямой порт рассчитан на локальное использование; внешний доступ требует аутентификации прокси, см. [Security](https://github.com/dev-sergeev/local-agent-chat/blob/main/SECURITY.md).
+
+Старые `.env`, `models.yaml` и каталог данных можно использовать через `localchat run --config-dir /path/to/checkout`. Сценарий `./scripts/run.sh` сохранён для существующих checkout и по-прежнему обрабатывает `.env` как shell-файл, включая прежние подстановки переменных. В новых установках используйте команды `localchat`. Запуск из исходников и проверки описаны в [Contributing](https://github.com/dev-sergeev/local-agent-chat/blob/main/CONTRIBUTING.md), выпуск — в [инструкции публикации](https://github.com/dev-sergeev/local-agent-chat/blob/main/docs/publishing.md).
+
+## Контекст и лимиты
+
+Параметры находятся в `AgentConfig` и могут задаваться через `.env`:
+
+| Переменная | По умолчанию | Назначение |
+|---|---:|---|
+| `AGENT_CONTEXT_TOKENS` | 16000 | Бюджет окна с резервом под ответ и инструменты |
+| `AGENT_SUMMARY_TRIGGER_TOKENS` | 10000 | Порог суммаризации сообщений |
+| `AGENT_KEEP_TOKENS` | 3000 | Бюджет последних сообщений, сохраняемых дословно |
+| `AGENT_SUMMARY_TOKENS` | 1000 | Максимальный ответ модели суммаризации |
+| `AGENT_MAX_OUTPUT_TOKENS` | 2000 | Максимальный ответ основной модели |
+| `AGENT_MAX_MODEL_CALLS` | 12 | Максимум обращений основной модели за один запрос |
+
+Укажите бюджет не больше реального окна выбранной модели. Счётчик использует консервативную оценку для текста и tool calls, поскольку у совместимых endpoint не всегда доступен точный токенизатор. Конфигурация проверяет запас для ответа, сводки и схем инструментов.
+
+Перед обращением к основной модели штатный `SummarizationMiddleware` заменяет старую часть контекста сводкой и сохраняет недавние сообщения, не разрывая tool-call/result пары. Предыдущая сводка включается в следующую. Длинный импортированный контекст суммируется порциями: старые сообщения не отбрасываются из-за стандартного лимита summarizer в 4000 токенов. Сводка не показывается как ответ пользователю и не заменяет полную историю UI.
+
+В `summary_options` профиля можно передать параметры модели только для суммаризации. В примере OpenRouter reasoning выключен через `extra_body.reasoning.enabled: false`: иначе небольшой лимит ответа может целиком уйти на reasoning и оставить пустую сводку. См. [параметры reasoning OpenRouter](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens). Для другого провайдера задайте поддерживаемые им параметры. Лимиты ответа и streaming управляются агентом.
+
+Пустая или обрезанная сводка, пустой ответ, ошибка модели и превышение бюджета последнего запроса завершают операцию с откатом. Слишком большой запрос следует разделить на части. Вывод одного файлового инструмента ограничен примерно 6000 символами; `read_file` поддерживает постраничное чтение, `grep` ищет буквальную строку.
+
+## Надёжность и хранение
+
+Provider SDK повторяет отдельные transient HTTP-запросы; полный ход агента и инструменты не переигрываются. Настройки: `LLM_MAX_RETRIES=3`, `LLM_REQUEST_TIMEOUT_SECONDS=60`, `LLM_STREAM_CHUNK_TIMEOUT_SECONDS=120`, `LLM_STREAM_RETRIES=1`, `LLM_AUXILIARY_TIMEOUT_SECONDS=30`. Дополнительная попытка streaming допустима только до первого полученного chunk. Для суммаризации действует та же политика без вложенного `with_retry`.
+
+В `APP_DATA_DIR` находятся:
+
+- `chainlit.sqlite3`: сообщения, шаги инструментов, вложения, названия; постоянный `stepOrder` сохраняет порядок даже при одинаковых временных метках.
+- `runtime-history.sqlite3`: только актуальные завершённые запросы/ответы и ссылки на предшествующее состояние.
+- `checkpoints.sqlite3`: выбор модели, текущий контекст и снимки контекста перед запросами. Граф ReAct между вызовами не хранит внутреннее состояние.
+- `sandboxes/`: файлы и снимки файлов; `blobs/`: сохранённые вложения Chainlit.
+
+Прежние чаты импортируются из актуальных запросов и ответов. Старые вызовы инструментов и внутренние графы не выполняются. Редактирование старого запроса восстанавливает предшествующую часть видимой истории. Старые режимы доступа исчезают; все чаты получают только чтение своей песочницы. Прежний индекс межчатового поиска удаляется, сохранённый `memory/MEMORY.md` больше не читается агентом. Внутренние старые LangGraph-таблицы могут оставаться в существующей базе как неиспользуемые данные.
+
+UI принимает до 20 файлов по 100 MiB; объём активных файлов чата ограничен 1 GiB. Коллизии имён получают суффикс. Удаление чата удаляет его активные данные и снимки нового контекста.
+
+## Где менять код
+
+| Задача | Файл |
+|---|---|
+| Сборка агента и цикл выполнения | `local_agent_chat/agent_execution.py` |
+| Суммаризация и бюджет контекста | `local_agent_chat/agent_context.py` |
+| Хранение контекста и откат | `local_agent_chat/agent_memory.py` |
+| Четыре инструмента чтения | `local_agent_chat/sandbox_tools.py` |
+| System prompt и заголовки | `local_agent_chat/prompts.py` |
+| Настройки и provider retry | `local_agent_chat/settings.py`, `local_agent_chat/llm_retry.py` |
+| Координация истории и UI | `local_agent_chat/runtime.py`, `local_agent_chat/chainlit_data.py`, `local_agent_chat/app.py` |
+
+[Архитектура](https://github.com/dev-sergeev/local-agent-chat/blob/main/docs/architecture.md), [термины](https://github.com/dev-sergeev/local-agent-chat/blob/main/CONTEXT.md), [ограничения доступа](https://github.com/dev-sergeev/local-agent-chat/blob/main/SECURITY.md), [разработка](https://github.com/dev-sergeev/local-agent-chat/blob/main/CONTRIBUTING.md), [результаты проверок](https://github.com/dev-sergeev/local-agent-chat/blob/main/docs/react-validation.md).

local_agent_chat-0.1.0/README.md

@@ -0,0 +1,109 @@
+# LocalChat
+
+Однопользовательский Chainlit UI и обычный ReAct-агент на LangChain: модель вызывает инструменты чтения загруженных файлов и формирует ответ. История диалога, сводка контекста и файлы сохраняются локально.
+
+Агент предоставляет ровно четыре инструмента: `ls`, `read_file`, `glob`, `grep`. Их виртуальный `/` — файлы текущего чата. Выход в файловую систему хоста, другие чаты, запись файлов, shell и выполнение кода недоступны. Субагентов, планировщика, файловой выгрузки контекста и общей долговременной памяти нет.
+
+Редактирование исторического запроса удаляет его прежний ответ и последующее продолжение. Контекст вместе со сводкой и файлами восстанавливается перед изменяемым запросом, после чего агент отвечает заново. Ошибка или Stop восстанавливают прежнее состояние. Одинаковый текст правки сохраняет весь диалог.
+
+## Установка и первый запуск
+
+Требуются Python **3.12–3.13**, Linux (или WSL2) и OpenAI-compatible модель с tool calling. Пакет содержит UI, переводы и все ресурсы приложения; клонировать репозиторий для запуска не нужно. Windows без WSL не поддерживается из-за требований файловой песочницы. macOS пока не входит в проверяемые платформы.
+
+После публикации в PyPI установите приложение через [pipx](https://pipx.pypa.io/stable/installation/):
+
+```bash
+pipx install --python python3.12 local-agent-chat
+localchat init
+localchat run
+```
+
+`init` запросит модель, адрес API и ключ. Для OpenAI-compatible endpoint имя модели имеет вид `openai:<model-id>`, например `openai:deepseek/deepseek-v4-flash-0731` для OpenRouter. Ключ вводится без отображения в терминале; секрет сессии создаётся автоматически. `run` покажет адрес UI, по умолчанию **http://127.0.0.1:8765/**. Остановка — `Ctrl+C`; `--open-browser` открывает браузер автоматически.
+
+До первого релиза можно установить собранный wheel: `pipx install --python python3.12 ./dist/local_agent_chat-0.1.0-py3-none-any.whl`. Альтернатива pipx — `python3.12 -m venv .venv`, активация окружения и `python -m pip install local-agent-chat`.
+
+Для локального API без ключа:
+
+```bash
+localchat init --no-input --model openai:your-model \
+  --base-url http://127.0.0.1:8000/v1 --no-api-key
+```
+
+Для автоматической настройки с ключом передайте его в `OPENAI_API_KEY` и используйте те же аргументы без `--no-api-key`. `--api-key-env MY_PROVIDER_KEY` выбирает другое имя переменной; `--no-streaming` отключает потоковый ответ. Полная справка: `localchat init --help`, `localchat run --help`.
+
+## Настройки, данные и обновление
+
+На Linux по умолчанию используются:
+
+- `~/.config/localchat/.env` — параметры запуска и ключи, права нового файла `0600`.
+- `~/.config/localchat/models.yaml` — профили моделей; ключи здесь не хранятся.
+- `~/.local/share/localchat/` — SQLite, история и вложения.
+
+Учитываются `XDG_CONFIG_HOME` и `XDG_DATA_HOME`. `--config-dir PATH` или `LOCALCHAT_CONFIG_DIR` выбирает другой каталог конфигурации, `--data-dir PATH` — каталог данных. Относительные пути из `.env` разрешаются относительно каталога конфигурации. Приоритет: аргументы запуска, затем переменные окружения, затем `.env`, затем значения по умолчанию. `.env` читается как данные: shell-команды и подстановки `${...}` не выполняются.
+
+Повторный `init` не перезаписывает настройки. Для смены модели или ключа отредактируйте конфигурацию и перезапустите приложение. Обновление: `pipx upgrade local-agent-chat`; перед обновлением остановите процесс и сделайте резервную копию каталогов конфигурации и данных. Установка и переустановка пакета их не затрагивают. Два процесса не могут одновременно открыть один каталог данных.
+
+Если запуск сообщает об отсутствующей конфигурации, выполните `localchat init`. Для занятого порта используйте `localchat run --port 8766`. Ошибки модели отображаются в UI и терминале; используйте endpoint с поддержкой tool calling и бюджетом контекста, подходящим выбранной модели.
+
+## JupyterHub и существующая установка
+
+Для прокси задайте **полный публичный префикс**:
+
+```bash
+localchat run --port 8765 \
+  --root-path "${JUPYTERHUB_SERVICE_PREFIX%/}/vscode/proxy/8765"
+```
+
+Здесь переменную раскрывает shell перед вызовом команды. В `.env` нужно записать уже готовый путь, например `/user/alice/vscode/proxy/8765`. Неверный префикс может привести к белому экрану из-за неправильных адресов JavaScript. Проверяйте UI по публичному адресу прокси. Прямой порт рассчитан на локальное использование; внешний доступ требует аутентификации прокси, см. [Security](https://github.com/dev-sergeev/local-agent-chat/blob/main/SECURITY.md).
+
+Старые `.env`, `models.yaml` и каталог данных можно использовать через `localchat run --config-dir /path/to/checkout`. Сценарий `./scripts/run.sh` сохранён для существующих checkout и по-прежнему обрабатывает `.env` как shell-файл, включая прежние подстановки переменных. В новых установках используйте команды `localchat`. Запуск из исходников и проверки описаны в [Contributing](https://github.com/dev-sergeev/local-agent-chat/blob/main/CONTRIBUTING.md), выпуск — в [инструкции публикации](https://github.com/dev-sergeev/local-agent-chat/blob/main/docs/publishing.md).
+
+## Контекст и лимиты
+
+Параметры находятся в `AgentConfig` и могут задаваться через `.env`:
+
+| Переменная | По умолчанию | Назначение |
+|---|---:|---|
+| `AGENT_CONTEXT_TOKENS` | 16000 | Бюджет окна с резервом под ответ и инструменты |
+| `AGENT_SUMMARY_TRIGGER_TOKENS` | 10000 | Порог суммаризации сообщений |
+| `AGENT_KEEP_TOKENS` | 3000 | Бюджет последних сообщений, сохраняемых дословно |
+| `AGENT_SUMMARY_TOKENS` | 1000 | Максимальный ответ модели суммаризации |
+| `AGENT_MAX_OUTPUT_TOKENS` | 2000 | Максимальный ответ основной модели |
+| `AGENT_MAX_MODEL_CALLS` | 12 | Максимум обращений основной модели за один запрос |
+
+Укажите бюджет не больше реального окна выбранной модели. Счётчик использует консервативную оценку для текста и tool calls, поскольку у совместимых endpoint не всегда доступен точный токенизатор. Конфигурация проверяет запас для ответа, сводки и схем инструментов.
+
+Перед обращением к основной модели штатный `SummarizationMiddleware` заменяет старую часть контекста сводкой и сохраняет недавние сообщения, не разрывая tool-call/result пары. Предыдущая сводка включается в следующую. Длинный импортированный контекст суммируется порциями: старые сообщения не отбрасываются из-за стандартного лимита summarizer в 4000 токенов. Сводка не показывается как ответ пользователю и не заменяет полную историю UI.
+
+В `summary_options` профиля можно передать параметры модели только для суммаризации. В примере OpenRouter reasoning выключен через `extra_body.reasoning.enabled: false`: иначе небольшой лимит ответа может целиком уйти на reasoning и оставить пустую сводку. См. [параметры reasoning OpenRouter](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens). Для другого провайдера задайте поддерживаемые им параметры. Лимиты ответа и streaming управляются агентом.
+
+Пустая или обрезанная сводка, пустой ответ, ошибка модели и превышение бюджета последнего запроса завершают операцию с откатом. Слишком большой запрос следует разделить на части. Вывод одного файлового инструмента ограничен примерно 6000 символами; `read_file` поддерживает постраничное чтение, `grep` ищет буквальную строку.
+
+## Надёжность и хранение
+
+Provider SDK повторяет отдельные transient HTTP-запросы; полный ход агента и инструменты не переигрываются. Настройки: `LLM_MAX_RETRIES=3`, `LLM_REQUEST_TIMEOUT_SECONDS=60`, `LLM_STREAM_CHUNK_TIMEOUT_SECONDS=120`, `LLM_STREAM_RETRIES=1`, `LLM_AUXILIARY_TIMEOUT_SECONDS=30`. Дополнительная попытка streaming допустима только до первого полученного chunk. Для суммаризации действует та же политика без вложенного `with_retry`.
+
+В `APP_DATA_DIR` находятся:
+
+- `chainlit.sqlite3`: сообщения, шаги инструментов, вложения, названия; постоянный `stepOrder` сохраняет порядок даже при одинаковых временных метках.
+- `runtime-history.sqlite3`: только актуальные завершённые запросы/ответы и ссылки на предшествующее состояние.
+- `checkpoints.sqlite3`: выбор модели, текущий контекст и снимки контекста перед запросами. Граф ReAct между вызовами не хранит внутреннее состояние.
+- `sandboxes/`: файлы и снимки файлов; `blobs/`: сохранённые вложения Chainlit.
+
+Прежние чаты импортируются из актуальных запросов и ответов. Старые вызовы инструментов и внутренние графы не выполняются. Редактирование старого запроса восстанавливает предшествующую часть видимой истории. Старые режимы доступа исчезают; все чаты получают только чтение своей песочницы. Прежний индекс межчатового поиска удаляется, сохранённый `memory/MEMORY.md` больше не читается агентом. Внутренние старые LangGraph-таблицы могут оставаться в существующей базе как неиспользуемые данные.
+
+UI принимает до 20 файлов по 100 MiB; объём активных файлов чата ограничен 1 GiB. Коллизии имён получают суффикс. Удаление чата удаляет его активные данные и снимки нового контекста.
+
+## Где менять код
+
+| Задача | Файл |
+|---|---|
+| Сборка агента и цикл выполнения | `local_agent_chat/agent_execution.py` |
+| Суммаризация и бюджет контекста | `local_agent_chat/agent_context.py` |
+| Хранение контекста и откат | `local_agent_chat/agent_memory.py` |
+| Четыре инструмента чтения | `local_agent_chat/sandbox_tools.py` |
+| System prompt и заголовки | `local_agent_chat/prompts.py` |
+| Настройки и provider retry | `local_agent_chat/settings.py`, `local_agent_chat/llm_retry.py` |
+| Координация истории и UI | `local_agent_chat/runtime.py`, `local_agent_chat/chainlit_data.py`, `local_agent_chat/app.py` |
+
+[Архитектура](https://github.com/dev-sergeev/local-agent-chat/blob/main/docs/architecture.md), [термины](https://github.com/dev-sergeev/local-agent-chat/blob/main/CONTEXT.md), [ограничения доступа](https://github.com/dev-sergeev/local-agent-chat/blob/main/SECURITY.md), [разработка](https://github.com/dev-sergeev/local-agent-chat/blob/main/CONTRIBUTING.md), [результаты проверок](https://github.com/dev-sergeev/local-agent-chat/blob/main/docs/react-validation.md).

local_agent_chat-0.1.0/SECURITY.md

@@ -0,0 +1,13 @@
+# Security
+
+Проект рассчитан на одного доверенного пользователя: локально или внутри защищённого JupyterHub. Фиксированный Local User в Chainlit полагается на аутентификацию внешнего прокси; прямой порт не является самостоятельной границей аутентификации.
+
+У агента есть только `ls`, `read_file`, `glob`, `grep` для файлов текущего чата. Абсолютные пути трактуются относительно виртуального корня загрузок, а не корня хоста. Компоненты пути открываются относительно дескриптора каталога с `O_NOFOLLOW`; `..`, симлинки и специальные файлы отвергаются. Инструментов записи, исполнения кода, shell, сети, чтения других чатов и Markdown-памяти нет.
+
+Файлы и цитируемые сообщения считаются недоверенными данными. Запрет выполнения инструкций из файлов задан в system prompt, а реальная область доступа ограничена самими инструментами. Выбранному model provider передаются запросы, соответствующий контекст и прочитанные фрагменты загруженных файлов. Прикладная песочница не заменяет изоляцию самого процесса контейнером или VM.
+
+Сводка сохраняется отдельно от полной истории UI. Ошибка или отмена её построения оставляет прежнее состояние. Устаревшие host-режимы не восстанавливаются из метаданных или checkpoint: старые чаты получают тот же ограниченный набор инструментов.
+
+Для сообщения об уязвимости используйте private security advisory репозитория; не публикуйте секреты или пользовательские данные в Issues.
+
+CLI слушает `127.0.0.1` по умолчанию. `localchat init` создаёт `.env` и профили с правами `0600`, новые каталоги — `0700`; ключи и пользовательские данные не входят в wheel или sdist. CLI читает `.env` без shell-подстановок. Старый `scripts/run.sh` сохраняет выполнение доверенного shell-файла для совместимости.

local_agent_chat-0.1.0/docs/adr/0001-persistent-chat-boundaries.md

@@ -0,0 +1,15 @@
+# Persist model, memory, and sandbox at the chat boundary
+
+Each chat selects one model profile and owns separate durable agent memory and a durable sandbox. This keeps resumed chats reproducible, prevents files from leaking between chats, and allows a revision of a user request to roll both memory and files back to the same pre-turn state.
+
+## Consequences
+
+Uploaded files live in the chat sandbox rather than SQLite. Deleting a chat deletes its sandbox, and supporting Chainlit's native revision of any user message requires both an agent checkpoint and a sandbox snapshot for every turn.
+
+A revision is a backend state transition, not merely a UI update: it truncates the active history after the edited request, restores agent memory and sandbox files to their matching pre-turn state, persists the replacement request, and reruns the agent to produce a new result. These changes must succeed as one coordinated operation; the agent must never continue from a mixture of revised messages, superseded memory, or stale filesystem side effects. Superseded turns remain in a technical audit log but disappear from the active chat timeline.
+
+Files attached to a revised request are imported only after its pre-turn Sandbox snapshot has been restored and before the Agent reruns. The import participates in the Revision transaction: provider failure, cancellation, or persistence failure restores the previously active Sandbox and removes tentative revised uploads.
+
+The runtime transaction remains open until Chainlit has persisted and committed the replacement UI continuation. It retains the current Agent checkpoint, Sandbox snapshot, and an exact snapshot of every active runtime Turn from the edited Turn onward. If rendering or the Chainlit commit fails after runtime history was replaced, that snapshot compensates the runtime write, restores its FTS sources and audit boundary, and restores Agent Memory and Sandbox before the per-Chat lock is released.
+
+LangGraph root graphs do not support using `checkpoint_ns` as an application-level memory branch. Every restore therefore materializes the selected checkpoint as the durable head of a new tracked LangGraph thread; restoring the pre-first-Turn state creates an empty thread. The active thread pointer is persisted before the next Turn, survives restart, and all threads owned by a Chat are removed on deletion.

local_agent_chat-0.1.0/docs/adr/0002-local-persistence-behind-adapters.md

@@ -0,0 +1,7 @@
+# Start with local persistence behind adapters
+
+The application starts with separate local SQLite persistence for Chainlit chat history and LangGraph agent checkpoints, linked by the Chainlit thread identifier. Storage boundaries remain replaceable because SQLite support for the Chainlit data layer is not an officially guaranteed deployment path, while SQLite checkpointing is supported by LangGraph.
+
+## Consequences
+
+Resuming a chat must restore both persistence planes without replaying the same history twice. The application will identify one local user silently so Chainlit can expose its built-in chat history without presenting a login screen.

local_agent_chat-0.1.0/docs/adr/0003-isolated-command-execution.md

@@ -0,0 +1,13 @@
+# Execute Extended-mode commands in a Chat-specific Python environment
+
+> Status: superseded by [ADR 0009](0009-scope-agent-file-reading-by-chat-mode.md).
+> Agent command/code execution and per-Chat Python environments were removed.
+> The text below records the former decision only.
+
+Only Extended Agent Mode exposes command execution. Python and shell commands execute through a local Deep Agents backend whose working directory is the Chat's `files/` directory, while absolute paths retain their real host meaning. Every Extended Chat owns a persistent `environment/venv` plus private `HOME`, temp and cache directories. The service environment is removed from `PATH`, user site-packages are disabled and normal `pip` operations target only the Chat venv. Read-only Chat creates no environment.
+
+## Consequences
+
+Chat dependencies survive application restarts and remain separate from revisioned files and internal artifacts; editing an earlier Turn rolls those revisioned directories back but does not uninstall packages. Deleting the Chat removes files, artifacts, snapshots, and its environment.
+
+This isolates Python dependencies, not arbitrary code. Extended commands and file tools can still access and modify the host filesystem and network with the service user's permissions, and those external changes are not rolled back by Revision. The deployment must provide a dedicated container or VM as the security boundary.

local_agent_chat-0.1.0/docs/adr/0004-bind-agent-mode-to-chat.md

@@ -0,0 +1,15 @@
+# Bind Agent Mode to the Chat at its first Turn
+
+Every Chat has an Agent Mode: `chat_files` by default or `host_files`. The UI may change the selection before the first user message. A synchronous Socket.IO pre-dispatch adapter orders Host Files-setting frames and the first valid message frame before Chainlit creates concurrent handler and persistence tasks. The message frame atomically locks the last accepted mode in the authoritative Chat registry; a failed or cancelled Turn does not unlock it. Stop, settings update, and Chat resume also recover the lock from a persisted request created by older or interrupted code. Chainlit metadata mirrors the value but never authorizes capabilities.
+
+Both modes expose exactly `ls`, `read_file`, `glob`, and `grep`. Chat Files maps Uploaded Files of the current Chat to virtual `/`; Host Files maps real `/` and therefore accepts process-readable absolute host paths. Explicit replacement Deep Agents filesystem middleware and read-only backends enforce the boundary on the main Agent and general-purpose subagent; the prompt only explains it. Project Skills are routed read-only to both modes and do not expand capabilities.
+
+The capability decision and removal of mutation/execution are recorded in [ADR 0009](0009-scope-agent-file-reading-by-chat-mode.md).
+
+Legacy `read_only` and `extended` values migrate to `host_files`, preserving the host-read scope those Chats previously had while deliberately removing mutation and execution. Their existing lock flag is preserved; schemas that predate mode selection migrate as locked `host_files`. Unrecognized values fail closed to `chat_files` without escalating their stored lock state.
+
+## Consequences
+
+Resume, restart, Revision, and model checkpoints cannot change a Chat's read scope. New modes require an explicit domain and migration change rather than a presentation-only switch. Host Files can disclose process-readable content to the model provider, while Revision restores only Chat-owned files and agent artifacts; the deployment container or VM remains the security boundary.
+
+Chainlit exposes no synchronous pre-message callback, so the adapter isolates one private `python-socketio` seam and verifies its expected `_handle_event` signature at startup. A dependency update that changes this seam fails explicitly rather than silently weakening the invariant.

local_agent_chat-0.1.0/docs/adr/0005-retrieve-global-memory-on-demand.md

@@ -0,0 +1,9 @@
+# Retrieve Global Memory from canonical active Turns on demand
+
+Global Memory is implemented as two read-only Agent tools: bounded search across other Chats and bounded reading of a selected result with nearby Turns. The tools query an SQLite FTS5 index derived transactionally from canonical active `turns`. They never search the current Chat or `superseded_turns`, and retrieved text is marked as untrusted historical data rather than instructions.
+
+The complete Chat History is not added to every model request. Embeddings and automatic extraction by a second model call remain deferred; FTS5 is local, deterministic, and effective for paths, identifiers, commands, errors, and quoted prior decisions. ADR 0008 separately introduces a small curated Markdown snapshot that is always loaded, without adding the full history.
+
+## Consequences
+
+Append, answer update, Revision, and Chat deletion update the index in the same SQLite transaction as canonical history, so stale branches disappear immediately. The Agent decides when prior context is relevant and first sees short candidates before reading a source. Semantic paraphrases may have lower recall than a future hybrid vector index, but no external embedding provider receives the history and the index can be rebuilt from active Turns.

local_agent_chat-0.1.0/docs/adr/0006-retry-llm-at-provider-boundary.md

@@ -0,0 +1,13 @@
+# Retry LLM calls at the provider boundary
+
+Every model created from a Model Profile uses the provider SDK's native retry at the boundary of one HTTP inference. The provider classifies transient connection failures, timeouts, rate limits and retryable HTTP statuses, applies exponential backoff with jitter, and honors `Retry-After`; the environment controls provider attempts, safe stream resumes, and request, stream-chunk, and auxiliary-call timeouts.
+
+Deep Agents' summarization middleware normally adds a second broad retry loop. The application replaces that inner runnable with the same provider-configured model, so `LLM_MAX_RETRIES` remains authoritative for each inference and provider retry loops cannot nest.
+
+Deep Agents exposes no public option for disabling only this inner loop. The adapter therefore verifies the supported middleware shape and fails at graph construction if it changes; dependency upgrades must keep the integration test green instead of silently restoring nested retries.
+
+## Consequences
+
+Provider retry stops once a stream has produced a chunk, because repeating a partially visible response would duplicate output. `LLM_STREAM_RETRIES` gives zero-chunk stream timeouts a separate finite budget around only the innermost model handler. It sits inside Deep Agents' summarization wrapper, so context offload, the Agent graph, Turn and tools are not replayed. Each new inference still has the per-inference provider budget. Permanent request, authentication, and validation errors fail immediately.
+
+Deep Agents' existing context-overflow recovery is a separate semantic operation: it may compact the Agent Memory context and issue a new inference. It is not a transport retry of the rejected HTTP inference and does not replay a completed tool call.

local_agent_chat-0.1.0/docs/adr/0007-load-project-skills-from-versioned-packages.md

@@ -0,0 +1,7 @@
+# Load Project Skills from versioned packages
+
+Project Skills live in `skills/<name>/SKILL.md` packages and are loaded through Deep Agents' native Skills source rather than being stored in Chat History, Uploaded Files or model configuration. This keeps procedural instructions reviewable with the application, supports progressive disclosure and gives the main Agent and its standard subagent one canonical source. Chat Files receives an explicit read-only route to this trusted source; Host Files can read the same absolute source directly.
+
+## Consequences
+
+Skills are trusted project instructions, shared by all Chats and available in both Agent Modes. They cannot expand a mode's filesystem scope, add tools, or make reference scripts executable. Their metadata enters Agent Memory on the first Turn, so a new or changed Skill becomes visible in a new Chat rather than mutating the behavior of an existing Chat midstream.

local_agent_chat-0.1.0/docs/adr/0008-keep-curated-long-term-memory-in-markdown.md

@@ -0,0 +1,7 @@
+# Keep curated Long-term Memory in bounded Markdown
+
+Long-term Memory is a small current snapshot in `APP_DATA_DIR/memory/MEMORY.md`, loaded through Deep Agents' `MemoryMiddleware` and updated by narrow `remember_context` and `forget_context` tools. This complements rather than replaces FTS history retrieval: the main Agent semantically decides what is durable during its existing inference, while stable keys, atomic upsert, strict limits and credential filtering keep the shared prompt context compact and reviewable without another extraction model or embeddings provider.
+
+## Consequences
+
+The middleware refreshes the file before every Turn so already-open Chats see changes. The general-purpose subagent receives a reference snapshot without the narrow mutation tools; those tools remain on the main Agent in both Agent Modes and do not grant generic filesystem writes. Host Files may read the managed Markdown by absolute path when the process permits it, but neither mode has a generic tool that can change it. Parallel updates are serialized across Agent instances before atomic replacement. Once accepted, a mutation reaches a durable decision even if the Turn is cancelled; a published change is an independent commit that survives a later Turn failure or cancellation, Revision, and deletion of the originating Chat. Correction or removal uses the same key or `forget_context`. The main model provider receives the bounded snapshot on every Turn; recognizable credentials are rejected or filtered, but users must still avoid placing secrets in the file. Memory remains untrusted prompt data: an Agent must not persist instructions copied from files or tool output, but this model-level rule is not a hard prompt-injection boundary.

local_agent_chat-0.1.0/docs/adr/0009-scope-agent-file-reading-by-chat-mode.md

@@ -0,0 +1,35 @@
+# Scope Agent file reading by Chat Mode and remove mutation/execution
+
+Every new Chat starts in `chat_files`. Its file tools see Uploaded Files of that
+Chat under virtual `/`, plus an explicit read-only route for trusted Project
+Skills. A separate private route serves Deep Agents' internal artifacts. Before
+the first user message, the user may select `host_files`, whose default read
+scope is real `/` and therefore supports absolute host paths available to the
+application process. The selected mode is immutable after the first Turn.
+
+Both modes expose exactly `ls`, `read_file`, `glob`, and `grep`. Explicit
+replacement `FilesystemMiddleware` instances give the main Agent and standard
+general-purpose subagent that same interface. Their backends reject file
+mutation even if an old checkpoint attempts a stale tool call. The application
+does not register `write_file`, `edit_file`, `delete`, or `execute`, and does not
+construct an Agent shell/code backend or a per-Chat Python environment. Project
+Skills remain available in both modes as instructions; `allowed-tools` metadata
+and reference scripts cannot expand these capabilities.
+
+The writable artifacts route is an internal middleware interface for bounded
+context offload, not an Agent-visible mutation capability. The narrow
+`remember_context` and `forget_context` tools likewise update only managed
+Long-term Memory and are not general filesystem tools.
+
+Legacy `read_only` and `extended` values migrate to `host_files` while retaining
+their stored lock state. This preserves their former ability to read host paths
+while intentionally dropping all mutation and execution. Schemas that predate
+mode selection migrate as locked; unknown values fail closed to `chat_files`.
+
+## Consequences
+
+Uploaded-file analysis works without disclosing unrelated host files by
+default. Host Files remains an explicit confidentiality-sensitive choice:
+process-readable content can be sent to the model provider. Revision can fully
+restore Chat-owned files and artifacts because Agent tools cannot change
+external host paths. ADR 0003's command-environment design is superseded.

local_agent_chat-0.1.0/docs/adr/0010-coordinate-native-edits-with-current-history.md

@@ -0,0 +1,7 @@
+# Coordinate the native editor with the current Chat History
+
+Chainlit's default editor schedules message updates and deletions independently, while its Message and Step APIs return before SQLite persistence finishes. LocalChat keeps the native UI but handles `edit_message` inside the Chat lock, stages recovery before truncation, waits for background writes before committing, and republishes the authoritative SQLite timeline on both success and rollback. Confirming identical text is a no-op, and the edit task participates in Stop cancellation.
+
+Only current Turn history is retained; this supersedes ADR 0001's permanent technical audit requirement. Temporary recovery rows protect an in-flight Revision and are discarded after its outcome is known; existing `superseded_turns` data is removed on startup without changing active Turns.
+
+Deep Agents' message state uses delta checkpoints, so copying a single raw checkpoint loses earlier messages. Restore materializes delta channels through the graph's state API before publishing a new memory thread. This retains the existing checkpoint-token format and restores old Chats without copying obsolete transcript branches. Regression coverage uses the real Deep Agents graph and SQLite, since a graph with ordinary full-state channels does not reproduce the failure. See the [LangGraph delta-channel contract](https://reference.langchain.com/python/langgraph/channels/delta).

local_agent_chat-0.1.0/docs/adr/0011-use-one-sandboxed-react-loop.md

@@ -0,0 +1,5 @@
+# Use one sandboxed ReAct loop with explicit persisted context
+
+Replace Deep Agents with LangChain `create_agent`, four read-only Sandbox tools and an explicit middleware list. Persist only messages and rolling summaries between Turns, keeping the graph ephemeral: Revision then restores a small application-owned snapshot instead of reconstructing internal checkpoint ancestry. This trades resuming a partially completed graph for simpler, predictable Turn rollback and context migration.
+
+This decision supersedes ADRs 0003–0005 and 0007–0009's agent capabilities, modes, subagents, skills and shared memory. ADR 0006's provider retry boundary and ADR 0010's coordinated UI commit remain. Existing Chats retain their visible history; legacy context is imported from completed requests and answers, never by executing obsolete tools or graph state. Every Chat now reads only its uploaded files, including Chats previously configured for host access.

local_agent_chat-0.1.0/docs/adr/0012-package-resources-and-separate-user-data.md

@@ -0,0 +1,3 @@
+# Ship immutable UI resources and keep user data outside the installation
+
+LocalChat is installed as a wheel with a Python CLI and all UI assets; configuration and durable Chat data live in explicit user directories. Chainlit requires a writable application root for temporary uploads, so a small CLI parent copies the shipped UI into a disposable workspace, starts Chainlit in a child process, forwards stop signals and holds a lock on the persistent data directory. Chainlit force-exits during shutdown, so the parent owns workspace cleanup. This costs a small asset copy at startup but keeps package upgrades independent of user data, avoids writes to site-packages, and prevents competing processes from corrupting cross-database Revision transactions.