@llmguard/opencode 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/MANUAL-TEST-G.md +167 -0
- package/README.md +334 -2
- package/RELEASE.md +122 -0
- package/bin/darwin-amd64/helper +0 -0
- package/bin/darwin-arm64/helper +0 -0
- package/bin/linux-amd64/helper +0 -0
- package/bin/linux-arm64/helper +0 -0
- package/bin/manifest.json +51 -0
- package/bin/windows-amd64/helper.exe +0 -0
- package/bin/windows-arm64/helper.exe +0 -0
- package/bridge/client.d.ts +55 -0
- package/bridge/client.js +425 -0
- package/bridge/framing.d.ts +19 -0
- package/bridge/framing.js +110 -0
- package/bridge/process.d.ts +38 -0
- package/bridge/process.js +378 -0
- package/bridge/protocol.d.ts +184 -0
- package/bridge/protocol.js +683 -0
- package/connection-catalog.d.ts +69 -0
- package/connection-catalog.js +287 -0
- package/connections-tui.d.ts +11 -0
- package/connections-tui.js +394 -0
- package/demasking.d.ts +2 -0
- package/demasking.js +445 -0
- package/gui-experimental.cjs +33 -0
- package/hook-trace.d.ts +2 -0
- package/hook-trace.js +35 -0
- package/index.d.ts +1 -0
- package/index.js +1 -0
- package/licenses/Go-LICENSE +27 -0
- package/messages.d.ts +230 -0
- package/messages.js +231 -0
- package/native/index.d.ts +1 -0
- package/native/index.js +1 -0
- package/native/tui.d.ts +1 -0
- package/native/tui.js +1 -0
- package/package.json +49 -4
- package/plugin-runtime.d.ts +3 -0
- package/plugin-runtime.js +3 -0
- package/plugin-settings.d.ts +77 -0
- package/plugin-settings.js +487 -0
- package/plugin.d.ts +41 -0
- package/plugin.js +10 -0
- package/response-diagnostics.d.ts +13 -0
- package/response-diagnostics.js +142 -0
- package/runtime/attachments.d.ts +4 -0
- package/runtime/attachments.js +19 -0
- package/runtime/errors.d.ts +18 -0
- package/runtime/errors.js +26 -0
- package/runtime/json.d.ts +14 -0
- package/runtime/json.js +243 -0
- package/runtime/limits.d.ts +2 -0
- package/runtime/limits.js +3 -0
- package/runtime/native-edit.d.ts +14 -0
- package/runtime/native-edit.js +73 -0
- package/runtime/runtime.d.ts +43 -0
- package/runtime/runtime.js +345 -0
- package/runtime/session-state.d.ts +13 -0
- package/runtime/session-state.js +73 -0
- package/runtime/text-layout.d.ts +9 -0
- package/runtime/text-layout.js +47 -0
- package/server.d.ts +1 -0
- package/server.js +1 -0
- package/settings-rpc.d.ts +511 -0
- package/settings-rpc.js +197 -0
- package/tui-messages.d.ts +1 -0
- package/tui-messages.js +84 -0
- package/tui.d.ts +17 -0
- package/tui.js +427 -0
- package/v1/hooks.d.ts +81 -0
- package/v1/hooks.js +97 -0
- package/v1/projection.d.ts +32 -0
- package/v1/projection.js +217 -0
- package/v1.d.ts +2 -0
- package/v1.js +2 -0
- package/v2/projection.d.ts +36 -0
- package/v2/projection.js +374 -0
- package/v2/server.d.ts +6 -0
- package/v2/server.js +633 -0
package/MANUAL-TEST-G.md
ADDED
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
# Ручная приёмка OpenCode с Go core
|
|
2
|
+
|
|
3
|
+
Текущая ручная матрица для OpenCode 0.1.0 с Go core; имя файла сохранено для
|
|
4
|
+
существующих ссылок. [RELEASE.md](RELEASE.md) описывает exports и упаковку.
|
|
5
|
+
Root entrypoint — native v2; программный v1 facade доступен через ./v1.
|
|
6
|
+
Старая установленная копия новой сборкой не обновляется.
|
|
7
|
+
|
|
8
|
+
Это инструкция, не отчёт о пройденной полной live-матрице. Synthetic helper/npm/ZIP
|
|
9
|
+
acceptance проверен на linux/amd64; пользователь подтвердил работу обоих билдов,
|
|
10
|
+
но каждый сценарий ниже требует отдельного результата. Codex имеет свою приёмку.
|
|
11
|
+
|
|
12
|
+
## 1. Подготовить отдельный тестовый запуск
|
|
13
|
+
|
|
14
|
+
1. Используйте linux/amd64 и Node.js 24. Go для установленного плагина не нужен.
|
|
15
|
+
Native mapping проверен типами SDK `@opencode/plugin` 2.1.4; запишите фактическую
|
|
16
|
+
версию своего OpenCode. Другие версии, ОС/архитектуры и musl пока unverified.
|
|
17
|
+
2. Подготовьте отдельную тестовую папку/сессию и тестовый Guard project/key.
|
|
18
|
+
Используйте только вымышленные строки и безвредные команды.
|
|
19
|
+
3. Зафиксируйте политику тестового проекта: какой synthetic input должен получить
|
|
20
|
+
allow, deny и transform. Например, настройте блокировку строки
|
|
21
|
+
`LLMGUARD_MANUAL_DENY_20261028` и маскирование тестового телефона `2025550147`.
|
|
22
|
+
Эти строки сами по себе не создают правил: ожидаемый результат должен следовать
|
|
23
|
+
из реально настроенной политики. Если детектору нужен иной synthetic sample,
|
|
24
|
+
используйте его и запишите ожидаемый результат. Политику не меняет плагин.
|
|
25
|
+
4. Для доказательства маскирования нужен доступ к безопасному тестовому provider
|
|
26
|
+
request capture или контролируемому mock provider. Экран чата и финальный
|
|
27
|
+
ответ сами по себе не доказывают, что provider не получил оригинал.
|
|
28
|
+
|
|
29
|
+
## 2. Распаковать и подключить свежий архив
|
|
30
|
+
|
|
31
|
+
Из корня checkout можно пересобрать архив:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
sh scripts/build-ts.sh && scripts/build.sh --all --output dist/artifacts && go run ./tools/pack pack
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Свежий архив — `dist/llmguard-opencode-<version>.zip`.
|
|
38
|
+
Распакуйте в новый отдельный каталог, например `/tmp/llmguard-manual/opencode-0.1.0`.
|
|
39
|
+
Сохраните executable permissions. Внутри находятся `index.js`, `tui.js`,
|
|
40
|
+
`runtime/bin` и manifest.
|
|
41
|
+
|
|
42
|
+
В распакованном корне выполните:
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
node verify.mjs
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Ожидается exit 0 и сообщение `files, entrypoints, codec and bundled helper verified`.
|
|
49
|
+
Это проверка файлов/handshake/локальной validation; она не обращается к Guard,
|
|
50
|
+
не включает защиту и не доказывает работу OpenCode hooks.
|
|
51
|
+
|
|
52
|
+
В конфигурации тестового OpenCode замените прежнюю запись LLMGuard абсолютным
|
|
53
|
+
путём нового распакованного корня:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"plugins": ["/tmp/llmguard-manual/opencode-0.1.0"]
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Сохраните другие plugins/settings. Не подключайте одновременно старую и новую
|
|
62
|
+
копии LLMGuard. Полностью остановите и запустите сервер OpenCode и TUI:
|
|
63
|
+
обычное переподключение TUI не доказывает загрузку новой сборки. Для удалённого OpenCode каталог и ключ должны находиться на его сервере.
|
|
64
|
+
Для native v2 выбирайте корень готового ZIP или npm build; программный v1 facade
|
|
65
|
+
теперь находится в `v1.js`, loader — в `plugin.js`.
|
|
66
|
+
|
|
67
|
+
## 3. Настроить через `/llmguard`
|
|
68
|
+
|
|
69
|
+
1. Откройте `/llmguard`. На чистой настройке защита выключена. Если сохранён
|
|
70
|
+
прежний enabled=true, сначала явно выключите защиту.
|
|
71
|
+
2. В «Настроить подключение» введите origin rules-engine и SID тестового проекта.
|
|
72
|
+
Используйте HTTPS; для Guard по HTTP отдельно выберите «Разрешить HTTP».
|
|
73
|
+
3. В «Ключ Guard» введите тестовый ключ. Ввод открытый; ключ должен оставаться в
|
|
74
|
+
памяти server instance, а не в connection storage, сообщениях или диагностике.
|
|
75
|
+
4. Проверьте «Статус подключения» и «Проверить связь с Guard». Connected=true при
|
|
76
|
+
deny означает доступный Guard, принявший решение политики, а не сбой транспорта.
|
|
77
|
+
Probe использует фиксированный текст, не содержимое вашей сессии.
|
|
78
|
+
5. Если status сообщает environment override, URL/SID берутся из окружения сервера
|
|
79
|
+
(`LLMGUARD_BASE_URL`, `LLMGUARD_PROJECT_SID`). Уберите override в тестовом запуске
|
|
80
|
+
либо используйте нужный тестовый endpoint. Не публикуйте токены из окружения.
|
|
81
|
+
6. Явно выберите «Включить защиту». Редактирование подключения/ключа через TUI
|
|
82
|
+
предварительно выключает защиту; после успешной настройки включите её снова.
|
|
83
|
+
|
|
84
|
+
## 4. Матрица проверок
|
|
85
|
+
|
|
86
|
+
| Проверка | Действие | Что считается успехом |
|
|
87
|
+
| --------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
88
|
+
| Allow | Отправьте строку, которую тестовая политика разрешает | Запрос проходит; есть соответствующий Guard event |
|
|
89
|
+
| Deny | Отправьте настроенный deny canary | Операция блокируется; canary не отправляется provider; есть Guard deny |
|
|
90
|
+
| Transform | Попросите повторить настроенный synthetic phone | Исходящий provider request содержит masked token вместо телефона |
|
|
91
|
+
| Restoration | Provider возвращает тот же masked token как текст ответа | В ответе этой сессии восстанавливается synthetic phone; оригинал не берётся из token syntax |
|
|
92
|
+
| Session scope | В другой новой сессии верните token из предыдущей | Старый token не раскрывается через bindings другой сессии |
|
|
93
|
+
| Tool before | Попросите вызвать безвредный `printf`/аналог с разрешённым текстом, затем с deny canary | Разрешённый вызов проходит; запрещённый не исполняется. Не подменяйте проверку tool.before обычным model deny |
|
|
94
|
+
| Tool args restoration | Передайте bound token в аргумент безвредного tool | Известный token восстанавливается перед свежей проверкой Guard; разрешение прошлой проверки не переиспользуется |
|
|
95
|
+
| Tool after | Безвредный tool выдаёт synthetic sample | Уже выполненный tool не откатывается; его текст наблюдается Guard и проверяется при следующем model request |
|
|
96
|
+
| Disable | Выключите защиту и повторите deny canary | Guard check не блокирует новый запрос. Этот шаг может отправить canary provider, поэтому нужен только вымышленный текст |
|
|
97
|
+
| Enable again | Включите защиту и повторите deny canary | Блокировка возвращается |
|
|
98
|
+
|
|
99
|
+
Для model hooks ожидаются source event names `session.context`,
|
|
100
|
+
`session.compaction`, `session.generate`, `session.title`; для tools —
|
|
101
|
+
`tool.execute.before`/`tool.execute.after`. Не каждый prompt обязан вызвать все
|
|
102
|
+
четыре model hook. Отдельно инициируйте compaction/title/generate средствами
|
|
103
|
+
вашей версии OpenCode. Если hook не удалось вызвать/наблюдать, отметьте unverified.
|
|
104
|
+
|
|
105
|
+
Не оценивайте transform только по ответу модели: она может не повторить token,
|
|
106
|
+
изменить его или не вызвать tool. Нужны provider boundary и фактический Guard event.
|
|
107
|
+
Attachments, media, metadata и числовые поля не должны переписываться; выберите
|
|
108
|
+
тест с такими полями, если ваша версия OpenCode позволяет их наблюдать.
|
|
109
|
+
|
|
110
|
+
## 5. Отказы и lifecycle
|
|
111
|
+
|
|
112
|
+
1. **Guard недоступен:** оставьте enabled=true, остановите только тестовый Guard
|
|
113
|
+
или используйте отдельный недоступный тестовый endpoint. Новый непустой
|
|
114
|
+
запрос должен блокироваться, а защита — оставаться включённой. Восстановите
|
|
115
|
+
Guard: повторный запрос должен проходить свежую проверку.
|
|
116
|
+
2. **Неверный ключ:** через TUI введите заведомо нерабочий тестовый ключ, снова
|
|
117
|
+
включите защиту. Probe/content не должны получать успешный allow из старого
|
|
118
|
+
подключения. Верните правильный ключ; включите защиту снова.
|
|
119
|
+
3. **Helper недоступен:** используйте только отдельную распакованную тестовую
|
|
120
|
+
копию. При работающем тестовом OpenCode, валидном подключении и enabled=true
|
|
121
|
+
переименуйте её `runtime/bin/linux-amd64/helper`, затем завершите только helper
|
|
122
|
+
PID этого экземпляра (например SIGTERM). Определите PID по полному пути и
|
|
123
|
+
родительскому процессу; не используйте массовый `pkill helper`. Новый непустой
|
|
124
|
+
запрос должен блокироваться, защита — оставаться включённой, TS fallback —
|
|
125
|
+
отсутствовать. Восстановите прежнее имя бинарника и полностью перезапустите
|
|
126
|
+
OpenCode: число автоматических рестартов ограничено. Пока имя изменено,
|
|
127
|
+
checksum verification ожидаемо не пройдёт. Не пытайтесь воспроизвести этот
|
|
128
|
+
случай простым закрытием TUI: его cleanup явно выключает защиту, и это уже
|
|
129
|
+
другой сценарий.
|
|
130
|
+
4. **Смена ключа/подключения:** после успешного transform смените ключ/профиль,
|
|
131
|
+
повторно включите защиту. Старый token не должен раскрыться через старые maps;
|
|
132
|
+
новый исходящий запрос должен пройти свежий Guard check.
|
|
133
|
+
5. **Перезапуск:** без `LLMGUARD_TOKEN`/`LLMGUARD_API_KEY` сессионный ключ теряется,
|
|
134
|
+
URL/SID и explicit enabled state сохраняются. При enabled=true и отсутствии
|
|
135
|
+
ключа содержимое блокируется до настройки или явного disable. С environment
|
|
136
|
+
key соединение настраивается заново, но bindings предыдущего процесса не живут.
|
|
137
|
+
6. **Unload:** отключение TUI plugin выключает защиту на том же server location;
|
|
138
|
+
полное завершение server plugin завершает его helper. Проверьте отсутствие
|
|
139
|
+
оставшегося helper этого экземпляра после остановки OpenCode.
|
|
140
|
+
|
|
141
|
+
Если Guard работает дольше 10 секунд, задайте `LLMGUARD_TIMEOUT_MS` в окружении
|
|
142
|
+
тестового сервера (например `30000`, максимум `180000`) и перезапустите его.
|
|
143
|
+
Нужный budget выбирается явно, таймаут не разрешает исходный запрос. При timeout
|
|
144
|
+
ожидается блокировка; повторный ручной запрос должен создавать новую проверку.
|
|
145
|
+
|
|
146
|
+
## 6. Что прислать для разбора
|
|
147
|
+
|
|
148
|
+
Для каждого случая запишите: actual OpenCode/Node/OS версии, hash архива,
|
|
149
|
+
сценарий, ожидаемый/фактический результат, был ли tool исполнен, подтверждён ли
|
|
150
|
+
provider boundary и Guard event. Секреты, исходные чувствительные данные и
|
|
151
|
+
полные provider payloads не нужны. Достаточно synthetic sample и correlation IDs.
|
|
152
|
+
|
|
153
|
+
Локальная диагностика — `${XDG_DATA_HOME:-~/.local/share}/opencode/log/llmguard-hooks.log`
|
|
154
|
+
либо явно заданный `LLMGUARD_TRACE_FILE`. Там только kinds/reason codes; наличие
|
|
155
|
+
записи само по себе не доказывает блокировку provider. Статусы каждого случая:
|
|
156
|
+
passed / failed / unverified. Результат текущей synthetic приёмки не переносится
|
|
157
|
+
на ручные проверки автоматически.
|
|
158
|
+
|
|
159
|
+
## Desktop GUI (native acceptance pending)
|
|
160
|
+
|
|
161
|
+
- Подключить собранный пакет глобально на Desktop с API SDK 2.2.5; проверить загрузку GUI и helper вне checkout.
|
|
162
|
+
- Открыть Settings → LLMGuard без активной сессии; сразу доступны поля подключения; проверить URL/SID/HTTP, скрытый ввод ключа, проверку связи, явное включение и выключение.
|
|
163
|
+
- Проверить allow/deny, masking/restoration запроса, stream ответа и tool args с реальным Guard.
|
|
164
|
+
- Открыть два проекта и TUI на одном сервере: ключ/подключение/переключатель общие, новый проект сразу защищён, закрытие одного UI не выключает защиту.
|
|
165
|
+
- Перейти из сессии в Settings: поля подключения доступны независимо от проекта; маскирование разных проектов не смешивает bindings и audit cwd.
|
|
166
|
+
- Проверить недоступный Guard, падение helper, отмену запроса, reload и restart сервера с потерей сессионного ключа.
|
|
167
|
+
- Проверить реальную установку на каждой заявляемой OS/CPU; cross-build и тесты не являются native acceptance.
|
package/README.md
CHANGED
|
@@ -1,3 +1,335 @@
|
|
|
1
|
-
#
|
|
1
|
+
# LLMGuard для OpenCode
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
V1 и v2 hooks используют bundled Go helper: Guard client, проверка coverage/correlation,
|
|
4
|
+
transform candidate и runner выполняются в Go. TS владеет native projections,
|
|
5
|
+
механическим применением подготовленных значений и session-scoped restoration.
|
|
6
|
+
Решения и маскирование выполняет rules-engine; локальных детекторов нет.
|
|
7
|
+
|
|
8
|
+
V1, v2 и настройки используют общий Go bridge. Проверка подключения и ключа,
|
|
9
|
+
configure и synthetic connection test выполняются helper. Один helper принадлежит
|
|
10
|
+
экземпляру server plugin; смена ключа/подключения очищает restoration maps.
|
|
11
|
+
Старый TS security core и его прямые exports удалены (этап G).
|
|
12
|
+
`src/v1` содержит v1 hooks/projections, `src/v2` — native OpenCode 2 mapping.
|
|
13
|
+
`v1.ts` сохраняет публичный v1 facade; root и `server.ts` — v2 entrypoint.
|
|
14
|
+
Release exports, migration и native acceptance: [RELEASE.md](RELEASE.md).
|
|
15
|
+
|
|
16
|
+
## V1: сборка и migration notes
|
|
17
|
+
|
|
18
|
+
Для v1 нужен npm-артефакт с готовым helper: при разработке выполните
|
|
19
|
+
`scripts/check.sh` или шаги из раздела «Готовый архив» (Go 1.27, Node 24).
|
|
20
|
+
Собранный пакет содержит binaries для linux/darwin/windows × amd64/arm64;
|
|
21
|
+
Go в runtime не нужен. Native execution проверен на linux/amd64; остальные
|
|
22
|
+
платформы и musl пока unverified. Бинарники не скачиваются и не компилируются
|
|
23
|
+
при загрузке плагина. Отсутствующий или недоступный helper блокирует проверку.
|
|
24
|
+
|
|
25
|
+
`createOpenCodeHooks(options: PluginOptions)` сохраняет facade, native v1 event
|
|
26
|
+
names и возвраты hooks. **Breaking change:** второй аргумент `Checker` удалён.
|
|
27
|
+
Передача второго аргумента, включая `undefined`, приводит к безопасной ошибке
|
|
28
|
+
загрузки; использовать её как обход Go core нельзя. Для тестов policy path
|
|
29
|
+
используются реальный helper и mock Guard HTTP server.
|
|
30
|
+
|
|
31
|
+
Bindings публикуются после синхронного native commit; изменения snapshot во
|
|
32
|
+
время check, конфликт bindings и readonly destination блокируют применение.
|
|
33
|
+
Tool-after остаётся observation: отказ Guard не откатывает выполненный tool.
|
|
34
|
+
|
|
35
|
+
## OpenCode 2: сборка и подключение
|
|
36
|
+
|
|
37
|
+
Сборка: `npm ci --ignore-scripts`, затем шаги из раздела «Готовый архив» (Go 1.27, Node 24).
|
|
38
|
+
API server/TUI/GUI проверяется типами официального `@opencode/plugin` **2.2.5**.
|
|
39
|
+
SDK нужен при разработке; server/TUI используют type imports, а GUI получает SDK и Solid от Desktop. GUI собирается Vite preset SDK в один CommonJS bundle. `skipLibCheck` в пакетном и тестовом
|
|
40
|
+
tsconfig отключает проверку сторонних declarations SDK, включая optional peers;
|
|
41
|
+
проверка нашего кода и соответствия SDK-контекстам остаётся включена.
|
|
42
|
+
|
|
43
|
+
В `opencode.json` указывается каталог с server/TUI/GUI entrypoints:
|
|
44
|
+
|
|
45
|
+
```json
|
|
46
|
+
{
|
|
47
|
+
"$schema": "https://opencode.ai/config.json",
|
|
48
|
+
"plugins": [
|
|
49
|
+
"/absolute/path/llmguard-agent-integrations/dist/opencode/package"
|
|
50
|
+
]
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
В каталоге находятся `index.js`, `tui.js` и `gui-experimental.cjs`; OpenCode загружает части своего интерфейса.
|
|
55
|
+
Сборка не меняет пользовательскую конфигурацию, trust и credentials.
|
|
56
|
+
Версия готового пакета берётся из native `package.json`; build ничего не публикует.
|
|
57
|
+
Корневой `dist/opencode/package/index.js` — native v2 server, `tui.js` — TUI.
|
|
58
|
+
Для v1 loader используется `plugin.js`; программный facade — `@llmguard/opencode/v1`.
|
|
59
|
+
Каталог `native` остаётся совместимым вариантом с парой entrypoints.
|
|
60
|
+
|
|
61
|
+
## Готовый архив
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
npm ci --ignore-scripts
|
|
65
|
+
sh scripts/build-ts.sh # tsc + GUI (vite) -> dist/build
|
|
66
|
+
scripts/build.sh --all --output dist/artifacts # шесть helper-ов, CGO=0 (или --target linux/amd64)
|
|
67
|
+
go run ./tools/pack pack # dist/package, dist/llmguard-opencode-<version>.tgz и .zip (+ .sha256)
|
|
68
|
+
go run ./tools/pack verify dist/llmguard-opencode-<version>.tgz
|
|
69
|
+
go run ./tools/pack verify --smoke dist/llmguard-opencode-<version>.zip
|
|
70
|
+
scripts/check.sh # всё выше плюс Go/TS тесты, lint, typecheck
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Нужны Go 1.27, Node.js 24 и npm 11. `dist/build` — TS-only staging; `dist/package` — npm tree (из него собран `.tgz`);
|
|
74
|
+
`.zip` — portable native plugin (только native v2 graph). `pack` ничего не компилирует: проверяет каждый helper по Go build
|
|
75
|
+
info (entrypoint, OS/CPU, без cgo), требует все шесть целей и отказывается
|
|
76
|
+
от helper-а, собранного против локального core (`--release`). Package-only не исправляет missing/stale inputs.
|
|
77
|
+
|
|
78
|
+
ZIP содержит JavaScript и готовые CGO=0 helpers для linux/darwin/windows ×
|
|
79
|
+
amd64/arm64, manifest helper и Go license. Go и npm-зависимости в runtime
|
|
80
|
+
не нужны. Версия берётся из `package.json`. Native execution пока проверен
|
|
81
|
+
только на linux/amd64; остальные платформы и musl unverified.
|
|
82
|
+
Архив содержит native `index.js`/`tui.js`/`gui-experimental.cjs`, граф runtime, `INSTALL.md`, пример
|
|
83
|
+
конфигурации, README и manifest с SHA-256 файлов. V1 и dev-зависимости исключены.
|
|
84
|
+
Сборка проверяет автономный импорт и запуск helper за пределами checkout; вручную можно запустить
|
|
85
|
+
`node verify.mjs` в распакованном каталоге (Node.js 24).
|
|
86
|
+
В `plugins` указывается распакованный корень пакета. Сборка не устанавливает
|
|
87
|
+
и не активирует плагин; публикация не выполняется.
|
|
88
|
+
|
|
89
|
+
## Меню `/llmguard`
|
|
90
|
+
|
|
91
|
+
TUI открывает расширенный штатный диалог (до 116 колонок, с ограничением
|
|
92
|
+
по доступной ширине терминала) со списком подключений: название, сервер, сокращённый SID,
|
|
93
|
+
наличие сохранённого ключа и отметка активного подключения. Поиск работает по
|
|
94
|
+
названию, полному адресу и полному SID. Выбор строки не меняет маршрут.
|
|
95
|
+
|
|
96
|
+
- **Ctrl+S** проверяет выбранное подключение и при успехе применяет его и включает
|
|
97
|
+
защиту для всех сессий сервера. Ошибка проверки оставляет активное подключение.
|
|
98
|
+
- **Enter** открывает редактор выбранного подключения, **Ctrl+N** создаёт новое.
|
|
99
|
+
Поля редактируются в произвольном порядке. Сохранение каталога не меняет
|
|
100
|
+
активный runtime snapshot. Escape сохраняет несекретный черновик до выгрузки TUI.
|
|
101
|
+
- **Ctrl+T** проверяет выбранное подключение без сохранения и переключения.
|
|
102
|
+
Используется отдельный Go helper и фиксированный тестовый текст; решение `deny`
|
|
103
|
+
не означает обрыв связи.
|
|
104
|
+
- **Ctrl+D** предлагает отключить защиту для всех сессий этого сервера.
|
|
105
|
+
- **Ctrl+R**, когда есть черновик, возвращает к его редактированию.
|
|
106
|
+
|
|
107
|
+
Ключ вводится обычным видимым prompt и сохраняется в локальном plugin storage
|
|
108
|
+
серверного OpenCode вместе с профилем. Это открытый текст, не системный keyring.
|
|
109
|
+
После перезапуска восстанавливаются ключи сохранённых профилей и отдельный
|
|
110
|
+
snapshot активного маршрута. Пустой ввод оставляет ключ именно этого подключения.
|
|
111
|
+
Полные ключи не возвращаются клиенту и не записываются в историю модели или логи.
|
|
112
|
+
В поле сохранённого ключа показываются первые четыре и последние два символа
|
|
113
|
+
через многоточие; ключи короче 10 символов полностью маскируются.
|
|
114
|
+
Каталог поддерживает до 100 подключений.
|
|
115
|
+
Существующее подключение показывается как OpenCode без записи при чтении.
|
|
116
|
+
|
|
117
|
+
Ключи и HTTP-проверки принадлежат Go helper; TUI управляет только настройками.
|
|
118
|
+
URL может включать префикс reverse proxy. При настройке через окружение редактирование
|
|
119
|
+
и переключение каталога недоступны. Если защита включена, но конфигурация потеряла
|
|
120
|
+
ключ, операции остаются заблокированными до исправления или явного отключения.
|
|
121
|
+
Неизвестный результат записи не повторяется автоматически; устаревшая ревизия
|
|
122
|
+
каталога отклоняется, черновик сохраняется. Desktop использует тот же каталог и те же RPC подключения; сохранение проекта
|
|
123
|
+
в обоих интерфейсах не меняет активный runtime snapshot.
|
|
124
|
+
|
|
125
|
+
SDK TUI 2.2.5 не предоставляет API языка: RU/EN автоматически выбираются по
|
|
126
|
+
локали терминального клиента (`LC_ALL`, `LC_MESSAGES`, `LANG`), английский — fallback.
|
|
127
|
+
Тема, поиск, фокус и клавиатурная навигация принадлежат штатному диалогу OpenCode.
|
|
128
|
+
В списке Ctrl-команды имеют приоритет перед командами поиска; при переходе
|
|
129
|
+
в редактор или закрытии списка этот перехват отключается.
|
|
130
|
+
Клавиатурные footer actions требуют поддержки соответствующего API хостом;
|
|
131
|
+
проверка типов SDK не заменяет приёмку на установленном OpenCode.
|
|
132
|
+
|
|
133
|
+
TUI и Desktop используют одно серверное подключение, сохранённый ключ и
|
|
134
|
+
переключатель защиты для всех проектов. Каждый location сохраняет собственные
|
|
135
|
+
restoration maps и audit cwd. Новые location сразу используют текущее подключение.
|
|
136
|
+
Закрытие или отключение UI не выключает защиту для других клиентов. Выключайте
|
|
137
|
+
её явным переключателем LLMGuard; последний выгруженный server instance освобождает helper.
|
|
138
|
+
Настройки передаются отдельным RPC и не отправляются как prompt модели.
|
|
139
|
+
|
|
140
|
+
Для ключа после рестартов можно использовать окружение **серверного** процесса:
|
|
141
|
+
`LLMGUARD_TOKEN` либо совместимый `LLMGUARD_API_KEY`. Введённый через TUI ключ имеет
|
|
142
|
+
приоритет и сохраняется после перезапуска. URL/SID также можно задать через `LLMGUARD_BASE_URL` и
|
|
143
|
+
`LLMGUARD_PROJECT_SID`; тогда оба берутся из окружения и редактирование профиля
|
|
144
|
+
заблокировано. `LLMGUARD_ALLOW_LOOPBACK_HTTP=true` явно разрешает локальный HTTP.
|
|
145
|
+
`LLMGUARD_TIMEOUT_MS` задаёт таймаут Guard-check (по умолчанию 10000; максимум 180000) — для развёртываний, где модельный PII-анализ на CPU занимает дольше
|
|
146
|
+
стандартного лимита; иначе длинные проверки завершаются fail-closed.
|
|
147
|
+
Частичная пара URL/SID не дополняется сохранёнными значениями.
|
|
148
|
+
|
|
149
|
+
При удалённом сервере `/llmguard` использует его location и RPC: профиль и ключ
|
|
150
|
+
применяются на сервере, не на машине терминала. Никакие настройки реального
|
|
151
|
+
OpenCode автоматически не устанавливаются и не активируются.
|
|
152
|
+
|
|
153
|
+
## OpenCode Desktop
|
|
154
|
+
|
|
155
|
+
Один пакет включает сервер, TUI и GUI. Для Desktop с GUI API SDK 2.2.5 добавьте
|
|
156
|
+
пакет в `plugins` глобального `~/.config/opencode/opencode.json(c)`.
|
|
157
|
+
Откройте Settings → LLMGuard или команду «LLMGuard: настройки и статус».
|
|
158
|
+
|
|
159
|
+
Desktop использует общий с TUI серверный каталог подключений. Слева — поиск
|
|
160
|
+
по названию, полному URL и полному SID, название, сервер, сокращённый SID,
|
|
161
|
+
наличие ключа и отметка активного проекта. Справа — открытый редактор;
|
|
162
|
+
при ширине области меньше 620 px он переносится под список. Язык RU/EN и тема
|
|
163
|
+
наследуются от клиента, отдельного переключателя языка нет.
|
|
164
|
+
|
|
165
|
+
Выбор строки только открывает её редактор. «Сохранить» обновляет каталог,
|
|
166
|
+
«Подключить» сначала проверяет сохранённый проект через Go helper и затем
|
|
167
|
+
применяет его ко всем сессиям сервера. «Проверить» в подвале не меняет маршрут.
|
|
168
|
+
Тест отправляет только фиксированный текст, без содержимого сессий.
|
|
169
|
+
Подвал всегда показывает активный маршрут, состояние защиты и результат операции.
|
|
170
|
+
«Отключить» требует подтверждения: запросы всех сессий этого сервера пойдут без Guard.
|
|
171
|
+
|
|
172
|
+
Ключ сохраняется в локальном plugin storage серверного OpenCode; в browser storage или chat он не записывается. Новый проект требует
|
|
173
|
+
ключ; пустой ключ при редактировании сохраняет ключ только этого проекта.
|
|
174
|
+
Поле очищается сразу при отправке и при выгрузке UI. Сервер не возвращает ключи.
|
|
175
|
+
|
|
176
|
+
Фоновое чтение каждые пять секунд сохраняет черновик. Смена выбранного проекта,
|
|
177
|
+
создание нового и отмена изменённого черновика требуют подтверждения сброса.
|
|
178
|
+
При изменении каталога другим клиентом устаревший черновик нельзя сохранить:
|
|
179
|
+
нужно отменить его и проверить актуальные данные. При неизвестном результате
|
|
180
|
+
записи форма не повторяет запрос автоматически; проверьте список перед повтором.
|
|
181
|
+
Если поиск скрывает выбранный проект, его нельзя проверить или подключить.
|
|
182
|
+
|
|
183
|
+
Настройки обращаются к серверу приложения напрямую, без выбора проекта OpenCode
|
|
184
|
+
или открытой сессии. Подключение и защита общие с TUI, подключённым к этому серверу.
|
|
185
|
+
GUI API экспериментальный: unit-тесты и браузерная демонстрация с подставными
|
|
186
|
+
host components не заменяют проверку на реальном Desktop. Native Desktop
|
|
187
|
+
покрытие запросов модели по этой проверке не подтверждалось.
|
|
188
|
+
|
|
189
|
+
## Адресное маскирование OpenCode 2
|
|
190
|
+
|
|
191
|
+
Hooks `context`, `compaction`, `generate`, `title` отправляют `model.before` с
|
|
192
|
+
проекцией `{texts: [...]}` и применяют только авторизованный кандидат к выбранным
|
|
193
|
+
строкам:
|
|
194
|
+
|
|
195
|
+
- `system[].text`;
|
|
196
|
+
- текст и reasoning в `messages[].content`, текстовая compaction summary;
|
|
197
|
+
- строки аргументов `tool-call.input`;
|
|
198
|
+
- текст/JSON/error value в `tool-result.result`, только текстовые элементы content.
|
|
199
|
+
|
|
200
|
+
`tool.execute.before` восстанавливает известные bindings этой сессии и проверяет
|
|
201
|
+
выбранные строковые аргументы через `tool.before` с `tool_input: {texts: [...]}`.
|
|
202
|
+
Для этого события OpenCode rules-engine сохраняет оригиналы при срабатывании
|
|
203
|
+
`mask`: маскирование защищает границу модели и не меняет локальные записи файлов
|
|
204
|
+
или аргументы инструментов. Правила `block`, ошибки и неполное покрытие продолжают
|
|
205
|
+
запрещать выполнение; исходные аргументы проверяются до запуска инструмента.
|
|
206
|
+
Результат инструмента снова маскируется перед следующим запросом к модели.
|
|
207
|
+
Числа и другие значения не сериализуются и не заменяются. `tool.execute.after`
|
|
208
|
+
только наблюдает: результат или сообщение ошибки записывается в Guard, но
|
|
209
|
+
никогда не блокирует, не скрывает и не «отменяет» уже выполненное действие
|
|
210
|
+
(как PostToolUse у Codex). Deny здесь — только запись в историю; маскирование
|
|
211
|
+
результата происходит в следующем `model.before`, который снова проверяет
|
|
212
|
+
выбранный текст перед моделью.
|
|
213
|
+
|
|
214
|
+
При `model.before` плагин добавляет bound
|
|
215
|
+
`source_payload.text_layout` (`version: 1`, `items: [{role, kind}]`),
|
|
216
|
+
выровненный по позициям `texts`: system/compaction-summary → `system/context`
|
|
217
|
+
(включая сообщения с ролью `system` внутри `messages`),
|
|
218
|
+
прежние сообщения → `history` (tool-result и сообщения с ролью `tool` → `tool`), а последний текст
|
|
219
|
+
последнего user-сообщения → `current_prompt`. Это позволяет истории Guard
|
|
220
|
+
показывать ввод пользователя как активное сообщение, а не инструкции или
|
|
221
|
+
контекст. Если user-текста в запросе нет или роль сообщения неизвестна,
|
|
222
|
+
метаданные не отправляются и действует прежнее поведение. Валидация схемы —
|
|
223
|
+
в rules-engine; layout не входит в coverage и связан digest запроса.
|
|
224
|
+
|
|
225
|
+
Прочие поля, metadata, IDs, неизвестные типы частей, media, ссылки и бинарные
|
|
226
|
+
данные остаются без изменений. Они не заявляются как проверенные. Tool definitions,
|
|
227
|
+
provider options/headers, raw native/encrypted provider данные и изменения других
|
|
228
|
+
плагинов после нашего hook не входят в покрытие. Дополнительный prompt compaction,
|
|
229
|
+
который OpenCode добавляет после hooks, также не входит в отправленную проекцию.
|
|
230
|
+
Отказ, ошибка, timeout и неприменимый кандидат для выбранных полей прерывают hook.
|
|
231
|
+
|
|
232
|
+
Bindings живут в памяти: до удаления сессии, смены подключения или unload;
|
|
233
|
+
максимум 128 сессий, 4096 bindings и 1 MiB символов на сессию.
|
|
234
|
+
|
|
235
|
+
## Восстановление ответа модели (v2)
|
|
236
|
+
|
|
237
|
+
Hook `http.response` восстанавливает только точные bindings текущей сессии в
|
|
238
|
+
ответе провайдера до того, как OpenCode разберёт поток: TUI, локальная история и
|
|
239
|
+
аргументы инструментов получают исходные значения, а не маркеры. Условия:
|
|
240
|
+
HTTP 200 и `Content-Type` `application/json` или `text/event-stream`. Наличие
|
|
241
|
+
`Content-Encoding` не мешает: fetch-рантаймы распаковывают тело прозрачно,
|
|
242
|
+
оставляя заголовок, поэтому решение принимается по первому байту тела —
|
|
243
|
+
JSON/SSE-текст (`{`, `[`, `data:`/`event:`/`id:`/`retry:`/`:`/BOM/пробел)
|
|
244
|
+
демаскируется, а сжатые magic bytes и бинарные тела проходят без изменений.
|
|
245
|
+
SSE восстанавливается по декодированным delta-полям OpenAI Chat Completions,
|
|
246
|
+
Responses и Anthropic Messages. Маркер удерживается между SSE-событиями,
|
|
247
|
+
отдельно для каждого choice/item/block и текстового поля; сетевые чанки могут
|
|
248
|
+
иметь произвольные границы. JSON-ответ буферизуется в пределах лимита.
|
|
249
|
+
В обоих случаях
|
|
250
|
+
восстановленный plaintext никогда не интерпретируется как новый маркер, оригинал
|
|
251
|
+
вставляется с JSON-экранированием, а рост тела ограничен. Из ответа убираются
|
|
252
|
+
`Content-Length`, `Content-MD5`, `Digest`, `ETag` и ставится `Cache-Control:
|
|
253
|
+
no-store`.
|
|
254
|
+
|
|
255
|
+
Если ответ нельзя восстановить (не 200, сжатие, другой media type, hook не
|
|
256
|
+
вызван для провайдера), ответ проходит без изменений — **маркеры остаются
|
|
257
|
+
видимыми**, блокировки нет. Диагностика hook'ов пишется в
|
|
258
|
+
`~/.local/share/opencode/log/llmguard-hooks.log` (путь можно переопределить
|
|
259
|
+
`LLMGUARD_TRACE_FILE`): только время, hook и код причины (`no_bindings`,
|
|
260
|
+
`media=…`, `binary_body`, `no_token_in_body`, `demasked=N`, …) — без содержимого
|
|
261
|
+
сообщений и секретов. Для диагностики разметки каждый HTTP-ответ получает
|
|
262
|
+
случайный `response` ID. Записи `markup channel=answer|reasoning|snapshot`
|
|
263
|
+
показывают флаги `before/after` для system-reminder, message, conversation и
|
|
264
|
+
инструкции заголовка: `1/1` — присутствовало до и после, `0/1` — появилось
|
|
265
|
+
после обработки. Сравниваются декодированные текстовые поля с учётом границ
|
|
266
|
+
delta; тексты, токены и ID сессий не записываются. `markup_complete` и число
|
|
267
|
+
наблюдавшихся полей позволяют отличить проверенный поток от неподдержанного
|
|
268
|
+
или неразобранного ответа. Диагностика завершается на terminal SSE-событии либо
|
|
269
|
+
при закрытии тела; отменённый раньше поток может не иметь итоговой записи.
|
|
270
|
+
`title.result` и `compaction.result`, выставленные
|
|
271
|
+
другим плагином, восстанавливаются из bindings перед сохранением. Маркеры в
|
|
272
|
+
аргументах инструментов дополнительно восстанавливаются перед новой проверкой
|
|
273
|
+
Guard (`tool.execute.before`). Строковые JSON-аргументы инструментов
|
|
274
|
+
(`arguments`/`partial_json`) остаются замаскированными в HTTP-ответе:
|
|
275
|
+
восстановление выполняется после разбора, перед проверкой инструмента.
|
|
276
|
+
JSON-экранированные маркеры (включая `\u003c`) поддерживаются в текстовых полях.
|
|
277
|
+
Переполнение лимита после начала чтения завершает поток ошибкой.
|
|
278
|
+
WebSocket-ответы и другие форматы delta не покрыты этим HTTP hook.
|
|
279
|
+
Реальная приёмка на установленном OpenCode 2 с
|
|
280
|
+
SSE-провайдером не выполнялась.
|
|
281
|
+
|
|
282
|
+
## Существующий OpenCode 1 entrypoint
|
|
283
|
+
|
|
284
|
+
`dist/opencode/package/plugin.js` сохраняет v1 hooks: messages/system transform, before/after tool
|
|
285
|
+
и text.complete. У него конфигурация через окружение, без нового TUI. В v1
|
|
286
|
+
text.complete восстанавливает bound tokens в завершённом тексте; это не проверка
|
|
287
|
+
финального ответа Guard. Формат конфигурации v1 — `plugin` с file URL к файлу,
|
|
288
|
+
а не v2 `plugins` с путём к каталогу.
|
|
289
|
+
|
|
290
|
+
## Проверки и границы приёмки
|
|
291
|
+
|
|
292
|
+
```sh
|
|
293
|
+
scripts/check.sh
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
Проверяются меню и отмена ввода, RPC, серверные настройки, отсутствие ключа в
|
|
297
|
+
storage/ответах, реальный Guard HTTP transport с локальным сервером, deny/error,
|
|
298
|
+
coverage, correlation, авторизованные замены и сохранение непроецируемых полей.
|
|
299
|
+
Для developer tests нужны Go 1.27 и Node 24 в PATH; `scripts/check.sh` явно готовит helper/package один раз; скрытого npm pretest нет. Сетевым тестам нужен loopback. Проверка типов официального SDK и callback-тесты
|
|
300
|
+
не заменяют реальную приёмку в установленном OpenCode 2 с моделью; она пока не
|
|
301
|
+
выполнена. Пакет не устанавливался и не активировался.
|
|
302
|
+
|
|
303
|
+
Источники: [OpenCode 2 plugins](https://dev.opencode.ai/v2/docs/build/plugins),
|
|
304
|
+
[TUI API](https://dev.opencode.ai/v2/docs/build/plugins/cli),
|
|
305
|
+
[RPC](https://dev.opencode.ai/v2/docs/build/plugins/rpc/),
|
|
306
|
+
[переход v1 → v2](https://dev.opencode.ai/v2/docs/build/plugins/migrate-v1).
|
|
307
|
+
[opencode-vibeguard](https://github.com/inkdust2021/opencode-vibeguard) использован
|
|
308
|
+
как референс точек v1-перехвата; его локальные правила и детекторы не перенесены.
|
|
309
|
+
|
|
310
|
+
## Изменения прямого API в 0.1.0
|
|
311
|
+
|
|
312
|
+
`@llmguard/opencode` экспортирует default native v2 server. `createOpenCodeHooks`,
|
|
313
|
+
`OpenCodeGuardError` и тип `PluginOptions` доступны через `@llmguard/opencode/v1`. Удалены `GuardClient`, `ClientError`,
|
|
314
|
+
`Operation`, `RunnerError`, `decodeRequest`/`decodeResponse`, `validateResult`,
|
|
315
|
+
`restorationValues`, `requestDigest`, `sameShape`, wire DTO/core interfaces и
|
|
316
|
+
связанные constants. Это breaking change для прямых пользователей прежнего
|
|
317
|
+
core facade. Подмены старых классов с изменённым sync/async contract нет.
|
|
318
|
+
Release version вручную задаётся в package.json; npm metadata имеет private:false,
|
|
319
|
+
root/test workspaces остаются private. Это не выполняет публикацию; таблица exports — в RELEASE.md.
|
|
320
|
+
|
|
321
|
+
Generic JSON codec/NumberToken, limits, session maps и provider restoration
|
|
322
|
+
остаются внутренними runtime-модулями, без package exports. Native v1/v2 hooks
|
|
323
|
+
используют bundled Go helper; fallback в TS при отказе helper отсутствует.
|
|
324
|
+
TLS проверяет Go: `NODE_EXTRA_CA_CERTS` больше не настраивает Guard transport;
|
|
325
|
+
для собственного CA используйте доверенное хранилище сертификатов на стороне
|
|
326
|
+
сервера OpenCode. Установку собственного CA эта сборка не выполняет.
|
|
327
|
+
|
|
328
|
+
Текущая ручная матрица: [MANUAL-TEST-G.md](MANUAL-TEST-G.md).
|
|
329
|
+
|
|
330
|
+
Системные hooks v1 и v2 добавляют общую инструкцию LLMGuard о точном копировании
|
|
331
|
+
маркеров, включая обе угловые скобки, до проверки Guard. Инструкция проверяется
|
|
332
|
+
и применяется вместе с остальным системным текстом; пустой system также поддержан.
|
|
333
|
+
Это подсказка модели, а не гарантия сохранности произвольно изменённых маркеров.
|
|
334
|
+
|
|
335
|
+
Версия принадлежит целому пакету и берётся из `package.json`. Helper не содержит встроенной версии и не согласовывает её через IPC; для аудита он читает манифест своего пакета. Комплектность бинарников проверяется по хешам.
|