@machine202502/dsh-choice 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 machine202502
+
+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,100 @@
-# Temporary Holding Version
+# dsh-choice
 
-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.
+A single-choice board inside the DeepSeek Harness chat, next to the built-in `ask_user_question`.
+
+```
+ask_user_choice({ title, subtitle?, options, noneLabel? })
+```
+
+Every option is **text**, an **image** or a **sound**. The card is posted as a normal chat
+row, the user presses the check icon on one row, and the choice comes back as an ordinary
+chat message that starts the next turn.
+
+## Behaviour
+
+- **one pick per board** — the check button on the chosen row; other rows become inert;
+- **«none of these»** — a trailing row with its label from `noneLabel`;
+- sounds and image previews stay usable after the pick;
+- **non-blocking** — the tool returns immediately, unlike `ask_user_question`, which waits
+  for the answer inside the turn;
+- **subagents are refused** — only the main agent can show a board:
+  `human interaction is unavailable while the calling agent is owned by another live agent…`.
+
+All visible text (title, subtitle, option titles and descriptions, `noneLabel`) comes from
+the agent, in the language of the conversation.
+
+## Card
+
+Rows: a 52 px preview (image thumbnail or ▶ button), the title and description, and the
+round check button on the right. Clicking an image opens a lightbox; pressing ▶ plays the
+sound with a plain `Audio` object, so there is no extra UI. A pick replaces the drafts
+carefully: the composer keeps its text, the choice is sent as its own message.
+
+## Options
+
+```jsonc
+{
+  "kind": "text",              // required: text | image | audio
+  "title": "Keep as is",       // row label
+  "description": "…",          // optional second line
+  "value": "…",                // text sent to the chat (defaults to title)
+  "src": "C:\\sounds\\a.wav"   // image/audio: http(s) URL or absolute local path
+}
+```
+
+Local files are copied into `%LOCALAPPDATA%\dsh-choice\media` and served over loopback.
+
+## Bridge
+
+`127.0.0.1:49236`:
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/status` | port and media counter |
+| `GET` | `/media/<file>` | served image or audio |
+| `POST` | `/attach` | copy a local file and return its URL |
+| `GET` | `/settings` | stored settings (`language`) |
+| `POST` | `/settings` | save `language`: `ru`, `en`, `zh` or `auto` |
+
+## Settings
+
+The plugin row config (`plugins.row.config`) holds one control: the interface language —
+Русский, English, 中文 or Авто. It is stored in `%LOCALAPPDATA%\dsh-choice\settings.json`
+and applies to the card and the form without a restart.
+
+The language is resolved in this order:
+
+1. the saved `language`, when it is `ru`, `en` or `zh`;
+2. `auto` — the application language: `document.documentElement.lang`, then
+   `navigator.language`; `ru*` → ru, `zh*` → zh, anything else → en;
+3. nothing stored — `ru`.
+
+All card text (title, subtitle, option titles and descriptions, `noneLabel`) comes from the
+agent, in the language of the conversation; only the plugin's own labels — the pick, play
+and open buttons and the settings row — follow the language above.
+
+## Languages
+
+The interface speaks Russian, English and Chinese. The language comes from the
+extension setting when it is `ru`, `en` or `zh`; `auto` follows the application
+language (`document.documentElement.lang`, then `navigator.language`; `ru*` → ru,
+`zh*` → zh, anything else → en); with nothing stored it is `ru`. Change it in
+**Plugins → Choice**; the value lives in `%LOCALAPPDATA%\dsh-choice\settings.json`
+and applies without a restart.
+
+## Screenshots
+
+![Plugin settings](docs/img/settings.jpg)
+
+## Install
+
+```json
+"@machine202502/dsh-choice": "^0.1.1"
+```
+
+and add `dsh-choice` to `dsh.profile.bundles`. A restart is required for the host half to
+load; the client half reloads with the page.
+
+## License
+
+MIT.

package/README.ru.md

@@ -0,0 +1,99 @@
+# dsh-choice
+
+Доска выбора одного варианта внутри чата DeepSeek Harness, рядом со встроенным
+`ask_user_question`.
+
+```
+ask_user_choice({ title, subtitle?, options, noneLabel? })
+```
+
+Каждый вариант — **текст**, **картинка** или **звук**. Карточка появляется обычной
+строкой в чате, пользователь нажимает галочку на одном ряду, и выбор приходит
+обычным сообщением, которое начинает следующий ход.
+
+## Поведение
+
+- **один выбор на доску** — галочка на выбранном ряду, остальные становятся
+  неактивными;
+- **«ничего из этого»** — дополнительный ряд, подпись берётся из `noneLabel`;
+- звуки и превью картинок остаются доступными после выбора;
+- **не блокирует** — инструмент возвращается сразу, в отличие от
+  `ask_user_question`, который ждёт ответа внутри хода;
+- **сабагентам отказано** — доску показывает только основной агент:
+  `human interaction is unavailable while the calling agent is owned by another live agent…`.
+
+Весь видимый текст (заголовок, подзаголовок, названия и описания вариантов,
+`noneLabel`) приходит от агента на языке разговора.
+
+## Карточка
+
+Ряды: превью 52 px (миниатюра картинки или кнопка ▶), заголовок и описание, справа
+круглая кнопка-галочка. Клик по картинке открывает просмотр; ▶ проигрывает звук
+обычным `Audio`, без дополнительного интерфейса. Выбор аккуратно заменяет черновики:
+текст в композере сохраняется, выбор уходит отдельным сообщением.
+
+## Варианты
+
+```jsonc
+{
+  "kind": "text",              // обязателен: text | image | audio
+  "title": "Оставить как есть",// подпись ряда
+  "description": "…",          // необязательная вторая строка
+  "value": "…",                // текст, который уйдёт в чат (по умолчанию title)
+  "src": "C:\\sounds\\a.wav"   // image/audio: http(s)-ссылка или абсолютный путь
+}
+```
+
+Локальные файлы копируются в `%LOCALAPPDATA%\dsh-choice\media` и отдаются через
+loopback.
+
+## Мост
+
+`127.0.0.1:49236`:
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| `GET` | `/status` | порт и счётчик медиа |
+| `GET` | `/media/<file>` | отдача картинки или звука |
+| `POST` | `/attach` | скопировать локальный файл и вернуть ссылку |
+| `GET` | `/settings` | сохранённые настройки (`language`) |
+| `POST` | `/settings` | сохранить `language`: `ru`, `en`, `zh` или `auto` |
+
+## Настройки
+
+В форме плагина (`plugins.row.config`) один контрол — язык интерфейса: Русский,
+English, 中文 или Авто. Хранится в `%LOCALAPPDATA%\dsh-choice\settings.json` и
+применяется к карточке и форме без перезапуска.
+
+Язык выбирается в таком порядке:
+
+1. сохранённый `language`, если это `ru`, `en` или `zh`;
+2. `auto` — язык приложения: `document.documentElement.lang`, затем
+   `navigator.language`; `ru*` → ru, `zh*` → zh, всё остальное → en;
+3. ничего не сохранено — `ru`.
+
+## Языки
+
+Интерфейс говорит на русском, английском и китайском. Язык берётся из настройки
+плагина, если это `ru`, `en` или `zh`; `auto` следует языку приложения
+(`document.documentElement.lang`, затем `navigator.language`; `ru*` → ru,
+`zh*` → zh, остальное → en); если ничего не сохранено — `ru`. Меняется в
+**Plugins → Choice**, хранится в `%LOCALAPPDATA%\dsh-choice\settings.json` и
+применяется без перезапуска.
+
+## Скриншоты
+
+![Настройки плагина](docs/img/settings.jpg)
+
+## Установка
+
+```json
+"@machine202502/dsh-choice": "^0.1.1"
+```
+
+и добавить `dsh-choice` в `dsh.profile.bundles`. Для загрузки хост-части нужен
+перезапуск; клиентская часть перезагружается вместе со страницей.
+
+## Лицензия
+
+MIT.

package/client.js

@@ -0,0 +1,569 @@
+window.__ModuleLoader__.load({
+  id: '@machine202502/dsh-choice',
+  factory(require) {
+    const React = require('react');
+    const h = React.createElement;
+
+    /** Loopback bridge of the host half; the saved language lives behind it. */
+    const PORT = 49236;
+    const base = `http://127.0.0.1:${PORT}`;
+
+    const STRINGS = {
+      ru: {
+        select: 'Выбрать',
+        play: 'Воспроизвести',
+        open: 'Открыть',
+        option: 'Вариант',
+        settingsTitle: 'Язык',
+        settingsHint: 'Авто — по языку приложения',
+        save: 'Сохранить',
+        saved: 'Сохранено',
+        saveFailed: 'Не удалось сохранить',
+        loading: 'Загрузка…',
+        auto: 'Авто',
+        langRu: 'Русский',
+        langEn: 'English',
+        langZh: '中文',
+      },
+      en: {
+        select: 'Select',
+        play: 'Play',
+        open: 'Open',
+        option: 'Option',
+        settingsTitle: 'Language',
+        settingsHint: 'Auto follows the application language',
+        save: 'Save',
+        saved: 'Saved',
+        saveFailed: 'Could not save',
+        loading: 'Loading…',
+        auto: 'Auto',
+        langRu: 'Русский',
+        langEn: 'English',
+        langZh: '中文',
+      },
+      zh: {
+        select: '选择',
+        play: '播放',
+        open: '打开',
+        option: '选项',
+        settingsTitle: '语言',
+        settingsHint: '自动 — 跟随应用界面语言',
+        save: '保存',
+        saved: '已保存',
+        saveFailed: '保存失败',
+        loading: '加载中…',
+        auto: '自动',
+        langRu: 'Русский',
+        langEn: 'English',
+        langZh: '中文',
+      },
+    };
+
+    /** The interface language; the shared default until the settings answer. */
+    let uiLanguage = 'ru';
+    const languageListeners = new Set();
+    const setLanguage = (next) => {
+      if (!STRINGS[next] || next === uiLanguage) return;
+      uiLanguage = next;
+      for (const listener of languageListeners) listener(next);
+    };
+
+    /** The application locale an `auto` preference follows. */
+    const detectLanguage = () => {
+      const raw = String(
+        (typeof document === 'undefined' ? '' : document.documentElement?.lang)
+        || (typeof navigator === 'undefined' ? '' : navigator.language)
+        || 'en',
+      ).toLowerCase();
+      if (raw.startsWith('ru')) return 'ru';
+      if (raw.startsWith('zh')) return 'zh';
+      return 'en';
+    };
+
+    /** Saved language first, `auto` second, the ru default when nothing is stored. */
+    const resolveLanguage = (settings) => {
+      const preference = settings?.language;
+      if (preference === 'ru' || preference === 'en' || preference === 'zh') return preference;
+      if (preference === 'auto') return detectLanguage();
+      return 'ru';
+    };
+
+    /** Read the stored language over the loopback bridge; failure keeps the default. */
+    const readSettings = async () => {
+      const response = await fetch(`${base}/settings`, { cache: 'no-store' });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      const body = await response.json();
+      setLanguage(resolveLanguage(body?.values));
+      return body;
+    };
+
+    // The card may render before the bridge answers; it re-renders on a language change.
+    void readSettings().catch(() => {});
+    // Another page part (or a second form instance) saved the language: re-read it.
+    window.addEventListener('dsh-choice:settings', () => { void readSettings().catch(() => {}); });
+
+    const ensureStyles = () => {
+      if (document.querySelector('style[data-plugin="choice-board"]')) return;
+      const tag = document.createElement('style');
+      tag.dataset.plugin = 'choice-board';
+      tag.textContent = `
+.cb-card { pointer-events: auto; display: flex; flex-direction: column; gap: 2px; padding: 6px 0; margin: 6px 0; width: 100%; box-sizing: border-box;
+  border: .5px solid var(--dsw-alias-border-l1, rgba(0,0,0,.10)); border-radius: 16px;
+  background: var(--dsw-alias-bg-l1, rgba(0,0,0,.015)); max-width: 640px; overflow: hidden; }
+.cb-head { display: flex; flex-direction: column; gap: 2px; padding: 10px 14px 8px; }
+.cb-title { font-size: 14px; font-weight: 600; }
+.cb-sub { font-size: 12px; opacity: .6; }
+.cb-row { display: flex; align-items: center; gap: 12px; width: 100%; box-sizing: border-box; padding: 10px 14px;
+  border-top: .5px solid var(--dsw-alias-border-l1, rgba(0,0,0,.07)); }
+.cb-row--selected { background: rgba(91,140,255,.08); }
+.cb-media { flex: none; width: 52px; height: 52px; border-radius: 10px; overflow: hidden; padding: 0;
+  border: none; background: var(--dsw-alias-bg-l2, rgba(0,0,0,.05)); cursor: pointer;
+  display: flex; align-items: center; justify-content: center; }
+.cb-media--static { cursor: default; }
+.cb-thumb { width: 100%; height: 100%; object-fit: cover; display: block; }
+.cb-play { width: 34px; height: 34px; border-radius: 999px; border: none; background: #0F1720; color: #5B8CFF;
+  font-size: 13px; cursor: pointer; display: inline-flex; align-items: center; justify-content: center; }
+.cb-play:disabled { opacity: .5; cursor: default; }
+.cb-row--selected .cb-play { color: #5B8CFF; }
+.cb-text { display: flex; flex-direction: column; gap: 2px; min-width: 0; flex: 1; }
+.cb-label { font-size: 13px; font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.cb-desc { font-size: 12px; line-height: 16px; opacity: .6; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+.cb-select { flex: none; width: 28px; height: 28px; padding: 0; border-radius: 999px; border: .5px solid var(--dsw-alias-border-l2, rgba(0,0,0,.18));
+  background: transparent; color: inherit; font-size: 13px; cursor: pointer;
+  display: inline-flex; align-items: center; justify-content: center; }
+.cb-select:hover { background: var(--dsw-alias-bg-l2, rgba(0,0,0,.05)); }
+.cb-select[disabled] { cursor: default; opacity: .5; }
+.cb-select--picked { border-color: #5B8CFF; color: #3b6fd8; background: rgba(91,140,255,.10); opacity: 1; }
+.cb-lightbox { position: fixed; inset: 0; z-index: 4000; display: flex; align-items: center; justify-content: center;
+  background: rgba(0,0,0,.55); backdrop-filter: blur(2px); }
+.cb-lightbox-card { max-width: min(90vw, 1100px); max-height: 88vh; display: flex; flex-direction: column; gap: 8px;
+  background: var(--dsw-alias-bg-l1, #fff); border-radius: 16px; padding: 10px; box-shadow: 0 24px 60px rgba(0,0,0,.35); }
+.cb-lightbox-img { max-width: 100%; max-height: 76vh; object-fit: contain; border-radius: 10px; display: block; }
+.cb-lightbox-cap { font-size: 12px; opacity: .7; padding: 0 4px 2px; }
+.cb-set { display: flex; flex-direction: column; gap: 14px; max-width: 520px; padding: 4px 0 8px; font-size: 13px; }
+.cb-set-row { display: flex; align-items: center; justify-content: space-between; gap: 24px; }
+.cb-set-hint { margin-top: 2px; font-size: 12px; line-height: 16px; opacity: .6; }
+.cb-set-select { height: 32px; padding: 0 10px; border: 1px solid var(--dsw-alias-border-l1, #dcdcdc); border-radius: 10px;
+  background: var(--dsw-alias-bg-base, #fff); color: inherit; font: inherit; outline: none; }
+.cb-set-actions { display: flex; align-items: center; gap: 12px; }
+.cb-set-save { height: 34px; padding: 0 16px; border: none; border-radius: 10px;
+  background: var(--dsw-alias-label-primary, #1f1f1f); color: var(--dsw-alias-bg-base, #fff); font: inherit; cursor: pointer; }
+.cb-set-save:disabled { opacity: .45; cursor: default; }
+.cb-set-status { font-size: 12px; opacity: .6; }
+.cb-set-status--error { color: #c0392b; opacity: 1; }
+`;
+      document.head.appendChild(tag);
+    };
+
+    const isUrl = (value) => /^https?:\/\//i.test(value ?? '');
+    /** Cards that already posted their pick in this page session. */
+    const sentCards = new Set();
+    const ourCalls = new Set();
+
+    const cardDefinition = {
+      kind: 'choice-board',
+      target: 'chat',
+      match: (event) => {
+        if (event?.type === 'tool/call') {
+          if (event.data?.name !== 'ask_user_choice') return null;
+          const id = String(event.data.callId);
+          ourCalls.add(id);
+          return { id, role: 'start' };
+        }
+        if (event?.type === 'tool/result') {
+          const callId = event.data?.message?.source?.callId;
+          if (typeof callId !== 'string' || !ourCalls.has(String(callId))) return null;
+          return { id: String(callId), role: 'update' };
+        }
+        return null;
+      },
+      start: (_context, match) => {
+        let args = {};
+        try {
+          args = JSON.parse(match.event.data?.arguments ?? '{}');
+        } catch {
+          args = {};
+        }
+        return { id: match.id, seq: match.event.seq, args, result: null, media: {} };
+      },
+      update: (context, match) => {
+        const text = (match.event.data?.message?.content ?? [])
+          .filter((item) => item && item.type === 'text')
+          .map((item) => item.text ?? '')
+          .join('\n');
+        const media = { ...(context.state.media ?? {}) };
+        const matchMedia = /\[media:(\[[\s\S]*\])\]/.exec(text);
+        if (matchMedia) {
+          try {
+            for (const item of JSON.parse(matchMedia[1])) {
+              if (typeof item?.index === 'number' && typeof item?.url === 'string') media[item.index] = item.url;
+            }
+          } catch {
+            // Malformed media map: the rows simply show placeholders.
+          }
+        }
+        return { ...context.state, result: text || null, media };
+      },
+      buildViewNode: (context) => {
+        const state = context.state;
+        if (!state) return null;
+        return {
+          key: context.key,
+          kind: 'choice-board',
+          id: context.id,
+          target: 'chat',
+          anchorSeq: state.seq,
+          location: context.location ?? { kind: 'chat' },
+          visibility: 'visible',
+          data: { ...state, nodeKey: context.key },
+        };
+      },
+    };
+
+    const visible = (node) => node instanceof HTMLElement && node.offsetParent !== null;
+
+    const findSendButton = () => [...document.querySelectorAll('button')]
+      .find((button) => /send|submit|отправ/i.test(button.getAttribute('aria-label') ?? button.title ?? ''));
+
+    const findComposer = () => {
+      const areas = [...document.querySelectorAll('[contenteditable="true"], textarea')].filter(visible);
+      if (areas.length === 0) return null;
+      const placeholder = areas.find((area) => /message|сообщени/i.test(
+        area.getAttribute('aria-placeholder') ?? area.getAttribute('data-placeholder') ?? area.getAttribute('placeholder') ?? ''));
+      if (placeholder) return placeholder;
+      const send = findSendButton();
+      if (send) {
+        const rect = send.getBoundingClientRect();
+        let best = null;
+        let bestDistance = Infinity;
+        for (const area of areas) {
+          const box = area.getBoundingClientRect();
+          const distance = Math.abs(box.bottom - rect.bottom) + Math.abs(box.right - rect.right) * 0.1;
+          if (distance < bestDistance) { bestDistance = distance; best = area; }
+        }
+        if (best) return best;
+      }
+      return areas[areas.length - 1] ?? null;
+    };
+
+    const composerText = (area) => (area instanceof HTMLTextAreaElement ? area.value : (area.innerText ?? area.textContent ?? '')).trim();
+
+    const selectAllContents = (area) => {
+      const selection = window.getSelection();
+      const range = document.createRange();
+      range.selectNodeContents(area);
+      selection?.removeAllRanges();
+      selection?.addRange(range);
+    };
+
+    const setComposerText = async (area, text) => {
+      area.focus();
+      await sleep(60);
+      if (area instanceof HTMLTextAreaElement) {
+        const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
+        setter?.call(area, text);
+        area.dispatchEvent(new Event('input', { bubbles: true }));
+        return;
+      }
+      selectAllContents(area);
+      await sleep(40);
+      document.execCommand('delete');
+      await sleep(40);
+      if (text.length > 0) {
+        selectAllContents(area);
+        document.execCommand('insertText', false, text);
+      }
+      await sleep(80);
+    };
+
+    const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+    const sendMessage = async (text) => {
+      const send = findSendButton();
+      const area = findComposer();
+      if (!area) return { ok: false, debug: 'no composer' };
+      const draft = composerText(area);
+      let inserted = false;
+
+      for (let attempt = 0; attempt < 3; attempt += 1) {
+        await setComposerText(area, text);
+        if (composerText(area) === text.trim()) { inserted = true; break; }
+        if (attempt === 1) {
+          area.textContent = '';
+          area.dispatchEvent(new Event('input', { bubbles: true }));
+          await sleep(60);
+          area.textContent = text;
+          area.dispatchEvent(new Event('input', { bubbles: true }));
+          await sleep(140);
+          if (composerText(area) === text.trim()) { inserted = true; break; }
+        }
+      }
+
+      if (!inserted) {
+        return { ok: false };
+      }
+
+      if (send) send.click();
+      else area.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', code: 'Enter', bubbles: true }));
+
+      await sleep(180);
+      if (draft && composerText(area) === '') {
+        await setComposerText(area, draft);
+      }
+      return { ok: true };
+    };
+
+
+    function ChoiceCard(props) {
+      ensureStyles();
+      const [language, setLanguageState] = React.useState(uiLanguage);
+      const t = STRINGS[language] ?? STRINGS.ru;
+      const data = props?.node?.data ?? {};
+      const args = data.args ?? {};
+      const callId = data.seq !== undefined && data.seq !== null ? String(data.seq) : (data.nodeKey ?? data.id ?? 'board');
+      const options = Array.isArray(args.options) ? args.options : [];
+      const [loaded, setLoaded] = React.useState({});
+      const [picked, setPicked] = React.useState(() => (sentCards.has(callId) ? '__sent__' : null));
+      const [playing, setPlaying] = React.useState(null);
+      const [zoom, setZoom] = React.useState(null);
+      const audioRef = React.useRef(null);
+
+
+      React.useEffect(() => {
+        languageListeners.add(setLanguageState);
+        setLanguageState(uiLanguage);
+        return () => { languageListeners.delete(setLanguageState); };
+      }, []);
+      React.useEffect(() => () => { audioRef.current?.pause?.(); }, []);
+      React.useEffect(() => {
+        if (!zoom) return undefined;
+        const onKey = (event) => { if (event.key === 'Escape') setZoom(null); };
+        document.addEventListener('keydown', onKey);
+        return () => document.removeEventListener('keydown', onKey);
+      }, [zoom]);
+
+      const sourceOf = (option, index) => (isUrl(option?.src) ? option.src : (data.media?.[index] ?? loaded[index] ?? null));
+      const labelOf = (option, index) => option?.title ?? option?.id ?? `${t.option} ${index + 1}`;
+      const valueOf = (option, index) => (typeof option?.value === 'string' ? option.value : labelOf(option, index));
+
+      const choose = async (option, index, none) => {
+        if (picked || sentCards.has(callId)) return;
+        sentCards.add(callId);
+        const text = none ? (args.noneLabel || '—') : valueOf(option, index);
+        const id = none ? '__none__' : String(option?.id ?? `option-${index + 1}`);
+        setPicked(id);
+        await sendMessage(text);
+      };
+
+      const togglePlay = (index, source) => {
+        if (!source) return;
+        if (audioRef.current && playing === index) {
+          audioRef.current.pause();
+          setPlaying(null);
+          return;
+        }
+        audioRef.current?.pause?.();
+        const audio = new Audio(source);
+        audioRef.current = audio;
+        audio.onended = () => setPlaying(null);
+        void audio.play();
+        setPlaying(index);
+      };
+
+      const selectButton = (selected, disabled, onClick, meta) => h('button', {
+        type: 'button',
+        className: `cb-select${selected ? ' cb-select--picked' : ''}`,
+        disabled,
+        title: t.select,
+        'aria-label': t.select,
+        'data-cb': 'pick',
+        'data-cb-value': meta?.value ?? '',
+        'data-cb-id': meta?.id ?? '',
+        'data-cb-none': meta?.none ? '1' : '0',
+        onPointerDown: (event) => { event.stopPropagation(); event.preventDefault(); onClick(); },
+        onClick: (event) => { event.stopPropagation(); onClick(); },
+      }, '✓');
+
+      const rows = options.map((option, index) => {
+        const id = String(option?.id ?? `option-${index + 1}`);
+        const selected = picked === id;
+        const kind = option?.kind ?? 'text';
+        const source = sourceOf(option, index);
+        let mediaBlock = null;
+        if (kind === 'image') {
+          mediaBlock = h('button', {
+            className: 'cb-media',
+            type: 'button',
+            'data-cb': 'image',
+            'data-cb-src': source ?? '',
+            'data-cb-title': labelOf(option, index),
+            title: t.open,
+            'aria-label': t.open,
+            onClick: (event) => { event.stopPropagation(); if (source) setZoom({ src: source, title: labelOf(option, index), desc: option?.description }); },
+          }, source ? h('img', { className: 'cb-thumb', src: source, alt: '' }) : null);
+        } else if (kind === 'audio') {
+          mediaBlock = h('button', {
+            className: 'cb-media',
+            type: 'button',
+            'data-cb': 'play',
+            'data-cb-src': source ?? '',
+            title: t.play,
+            'aria-label': t.play,
+            disabled: !source,
+            onClick: (event) => { event.stopPropagation(); togglePlay(index, source); },
+          }, h('span', { className: 'cb-play' }, playing === index ? '❚❚' : '▶'));
+        }
+
+        return h('div', { key: id, className: `cb-row${selected ? ' cb-row--selected' : ''}` },
+          mediaBlock,
+          h('span', { className: 'cb-text' },
+            h('span', { className: 'cb-label' }, labelOf(option, index)),
+            option?.description ? h('span', { className: 'cb-desc' }, option.description) : null,
+          ),
+          selectButton(selected, Boolean(picked), () => void choose(option, index, false), { value: valueOf(option, index), id }),
+        );
+      });
+
+      const noneSelected = picked === '__none__';
+      const noneRow = h('div', { className: `cb-row${noneSelected ? ' cb-row--selected' : ''}` },
+        h('span', { className: 'cb-text' }, h('span', { className: 'cb-label' }, args.noneLabel || '—')),
+        selectButton(noneSelected, Boolean(picked), () => void choose(null, -1, true), { value: args.noneLabel || '', id: '__none__', none: true }),
+      );
+
+      const lightbox = zoom
+        ? h('div', {
+            className: 'cb-lightbox',
+            onClick: () => setZoom(null),
+          },
+            h('div', { className: 'cb-lightbox-card', onClick: (event) => event.stopPropagation() },
+              h('img', { className: 'cb-lightbox-img', src: zoom.src, alt: zoom.title }),
+              (zoom.title || zoom.desc)
+                ? h('span', { className: 'cb-lightbox-cap' }, [zoom.title, zoom.desc].filter(Boolean).join(' — '))
+                : null,
+            ),
+          )
+        : null;
+
+      return h('div', { className: 'cb-card' },
+        h('div', { className: 'cb-head' },
+          args.title ? h('span', { className: 'cb-title' }, args.title) : null,
+          args.subtitle ? h('span', { className: 'cb-sub' }, args.subtitle) : null,
+        ),
+        ...rows,
+        noneRow,
+        lightbox,
+      );
+    }
+
+    /**
+     * The settings row: one language select, saved to the host bridge so the
+     * board and the form agree without a restart.
+     */
+    function ChoiceSettings() {
+      ensureStyles();
+      const [state, setState] = React.useState({ status: 'loading', values: {}, defaults: {} });
+      const [saving, setSaving] = React.useState(false);
+      const [notice, setNotice] = React.useState({ text: '', error: false });
+      const [language, setLanguageState] = React.useState(uiLanguage);
+
+      React.useEffect(() => {
+        let alive = true;
+        languageListeners.add(setLanguageState);
+        readSettings()
+          .then((body) => {
+            if (alive) setState({ status: 'ready', values: body?.values ?? {}, defaults: body?.defaults ?? {} });
+          })
+          .catch(() => {
+            if (alive) setState({ status: 'error', values: {}, defaults: {} });
+          });
+        return () => {
+          alive = false;
+          languageListeners.delete(setLanguageState);
+        };
+      }, []);
+
+      const t = STRINGS[language] ?? STRINGS.ru;
+      const chosen = state.values.language ?? state.defaults.language ?? 'ru';
+
+      const save = async () => {
+        setSaving(true);
+        setNotice({ text: '', error: false });
+        try {
+          const response = await fetch(`${base}/settings`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ language: chosen }),
+          });
+          const body = await response.json();
+          if (!response.ok) throw new Error(body.error ?? `HTTP ${response.status}`);
+          setState({ status: 'ready', values: body.values ?? {}, defaults: body.defaults ?? {} });
+          setLanguage(resolveLanguage(body?.values));
+          setNotice({ text: (STRINGS[uiLanguage] ?? STRINGS.ru).saved, error: false });
+          window.dispatchEvent(new CustomEvent('dsh-choice:settings'));
+        } catch (error) {
+          setNotice({ text: `${(STRINGS[uiLanguage] ?? STRINGS.ru).saveFailed}: ${String(error?.message ?? error)}`, error: true });
+        } finally {
+          setSaving(false);
+        }
+      };
+
+      if (state.status === 'loading') {
+        return h('div', { className: 'cb-set' }, h('span', { className: 'cb-set-status' }, t.loading));
+      }
+
+      const options = [
+        ['ru', t.langRu],
+        ['en', t.langEn],
+        ['zh', t.langZh],
+        ['auto', t.auto],
+      ];
+
+      return h('div', { className: 'cb-set' },
+        h('div', { className: 'cb-set-row' },
+          h('div', null,
+            h('div', null, t.settingsTitle),
+            h('div', { className: 'cb-set-hint' }, t.settingsHint),
+          ),
+          h('select', {
+            className: 'cb-set-select',
+            value: chosen,
+            'aria-label': t.settingsTitle,
+            onChange: (event) => setState((previous) => ({ ...previous, values: { ...previous.values, language: event.target.value } })),
+          }, options.map(([value, text]) => h('option', { key: value, value }, text))),
+        ),
+        h('div', { className: 'cb-set-actions' },
+          h('button', { type: 'button', className: 'cb-set-save', onClick: save, disabled: saving === true },
+            saving ? '…' : t.save),
+          notice.text ? h('span', { className: `cb-set-status${notice.error ? ' cb-set-status--error' : ''}` }, notice.text) : null,
+        ),
+      );
+    }
+
+    return {
+      inject: ['slots', 'uiConversation'],
+      apply(ctx) {
+        try {
+          ctx.uiConversation.events.register(cardDefinition);
+        } catch (error) {
+          console.warn('dsh-choice: chat node definition failed', error);
+        }
+        try {
+          ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+            name: 'conversation.chat.node',
+            key: 'choice-board',
+          }, ChoiceCard));
+        } catch (error) {
+          console.warn('dsh-choice: chat node view failed', error);
+        }
+        try {
+          ctx.slots.inject('plugins.row.config', () => ctx.slots.register({
+            name: 'plugins.row.config',
+            key: 'dsh-choice#choice',
+          }, ChoiceSettings));
+        } catch (error) {
+          console.warn('dsh-choice: settings form failed', error);
+        }
+      },
+    };
+  },
+});

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+- insert:
+    - id: choice
+      name: '@machine202502/dsh-choice'
+      config:
+        bridgePort: 49236

package/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Choice">
+  <rect x="2" y="2" width="60" height="60" rx="16" fill="#0F1720"/>
+  <circle cx="18" cy="20" r="2.6" fill="#93B4FF"/>
+  <circle cx="18" cy="32" r="2.6" fill="#93B4FF"/>
+  <circle cx="18" cy="44" r="2.6" fill="#93B4FF"/>
+  <path d="M25 20h21M25 32h21" stroke="#5B8CFF" stroke-width="3.4" stroke-linecap="round"/>
+  <path d="M25 44h12" stroke="#5B8CFF" stroke-width="3.4" stroke-linecap="round" opacity=".45"/>
+  <path d="M41 44l4 4 8-9" stroke="#93B4FF" stroke-width="3.6" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+</svg>

package/index.js

@@ -0,0 +1,282 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { join, dirname, extname, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { createServer } from 'node:http';
+
+export const name = 'dsh-choice';
+export const inject = ['tools'];
+
+/** Language choices stored in settings.json; `auto` follows the application locale. */
+const LANGUAGES = ['ru', 'en', 'zh', 'auto'];
+const DEFAULT_SETTINGS = { language: 'ru' };
+
+/** Read a JSON file, returning null instead of throwing on a missing or broken one. */
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Write JSON through a temporary file so a crash never leaves half a file. */
+function writeJson(file, value) {
+  mkdirSync(dirname(file), { recursive: true });
+  const temporary = `${file}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  renameSync(temporary, file);
+}
+
+const dataRoot = () => {
+  const base = process.env.LOCALAPPDATA
+    || (process.platform === 'darwin' ? join(homedir(), 'Library', 'Application Support') : join(homedir(), '.local', 'share'));
+  return join(base, 'dsh-choice');
+};
+
+const TYPES = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.wav': 'audio/wav',
+  '.mp3': 'audio/mpeg',
+  '.ogg': 'audio/ogg',
+  '.m4a': 'audio/mp4',
+};
+
+/**
+ * A choice board printed as the final message of a turn.
+ *
+ * The tool renders the card and returns immediately; the user's click posts a
+ * normal chat message, which starts the next turn. The card itself never blocks
+ * the agent and becomes inert after a pick.
+ */
+export function apply(ctx, config = {}) {
+  const root = dataRoot();
+  const mediaDir = join(root, 'media');
+  mkdirSync(mediaDir, { recursive: true });
+  const port = Number.isFinite(config.bridgePort) ? Number(config.bridgePort) : 49236;
+  const base = `http://127.0.0.1:${port}`;
+  const media = new Map();
+  const settingsFile = join(root, 'settings.json');
+
+  /** The stored settings, falling back to the defaults on any damage. */
+  const loadSettings = () => {
+    const stored = readJson(settingsFile);
+    const language = LANGUAGES.includes(stored?.language) ? stored.language : DEFAULT_SETTINGS.language;
+    return { language };
+  };
+  const saveSettings = (input) => {
+    const language = LANGUAGES.includes(input?.language) ? input.language : DEFAULT_SETTINGS.language;
+    const next = { language };
+    writeJson(settingsFile, next);
+    return next;
+  };
+
+  const attach = (source) => {
+    if (typeof source !== 'string' || !source) return null;
+    if (/^https?:\/\//i.test(source)) return source;
+    if (!isAbsolute(source) || !existsSync(source)) return null;
+    const ext = extname(source).toLowerCase();
+    if (!TYPES[ext]) return null;
+    const size = statSync(source).size;
+    if (size > 25 * 1024 * 1024) return null;
+
+    // The file may be mid-rewrite by the agent (Windows sharing violations);
+    // retry briefly instead of returning a half-written snapshot.
+    let bytes = null;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+      try {
+        bytes = readFileSync(source);
+        break;
+      } catch (error) {
+        if (attempt === 3) throw new Error(`cannot read ${source}: ${error?.code ?? error}`);
+        sleepSync(120);
+      }
+    }
+    if (bytes === null) return null;
+
+    // Content-addressed: the same path with new bytes gets a new URL, so a
+    // rewritten file never resolves to the previous snapshot.
+    const name = `${createHash('sha256').update(bytes).digest('hex').slice(0, 12)}${ext}`;
+    const target = join(mediaDir, name);
+    if (!existsSync(target) || statSync(target).size !== bytes.length) {
+      writeFileSync(target, bytes);
+    }
+    media.set(name, TYPES[ext]);
+    return `${base}/media/${name}`;
+  };
+
+  const sleepSync = (ms) => {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+      // Busy-wait is fine here: this runs once per option during tool setup.
+    }
+  };
+
+  const tool = {
+    name: 'ask_user_choice',
+    description:
+      'Ask the user to pick exactly one option when the options are images, sounds, or mixed media, '
+      + 'or when the turn should end and the user can answer whenever they want. '
+      + 'For plain-text choices prefer the standard ask_user_question. '
+      + 'Options are text, image or audio. The user presses the pick button on one row; a normal chat message '
+      + 'with that choice is posted and starts the next turn. After that the card stops accepting picks, '
+      + 'but its sounds and image previews stay playable. A trailing "none of these" row is always added - '
+      + 'pass its label as noneLabel. This tool returns immediately and never blocks the turn, unlike '
+      + 'ask_user_question which waits for the answer. Write every visible text (title, subtitle, option titles '
+      + 'and descriptions, noneLabel) in the language you are speaking with the user.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        title: { type: 'string', description: 'Board heading' },
+        subtitle: { type: 'string', description: 'Optional one-line hint under the heading' },
+        options: {
+          type: 'array',
+          description: 'Two to eight options',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              id: { type: 'string' },
+              kind: { type: 'string', enum: ['text', 'image', 'audio'] },
+              title: { type: 'string' },
+              description: { type: 'string' },
+              value: { type: 'string', description: 'Text sent to the chat for kind=text' },
+              src: { type: 'string', description: 'Image or audio: http(s) URL or absolute local path' },
+            },
+            required: ['kind'],
+          },
+        },
+        noneLabel: { type: 'string', description: 'Label of the trailing "none of these" row' },
+      },
+      required: ['options'],
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          boardId: { type: 'string' },
+          shown: { type: 'boolean' },
+          media: {
+            type: 'array',
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: { index: { type: 'number' }, url: { type: 'string' } },
+            },
+          },
+        },
+        required: ['shown'],
+      },
+      render: (_args, value) => [{ type: 'text', text: `[media:${JSON.stringify(value.media ?? [])}]` }],
+    },
+    async execute(args, exec) {
+      const depth = exec?.agent?.options?.subagentDepth;
+      const isSubagent = exec?.parent !== undefined
+        || exec?.agent?.address !== undefined
+        || (typeof depth === 'number' && depth > 0);
+      if (isSubagent) {
+        throw new Error('human interaction is unavailable while the calling agent is owned by another live agent; include the unresolved question or decision in the child agent\'s final result');
+      }
+      const options = Array.isArray(args?.options) ? args.options : [];
+      if (options.length < 2) throw new Error('options must contain at least two items');
+      if (options.length > 8) throw new Error('at most 8 options per board');
+      const media = [];
+      options.forEach((option, index) => {
+        if (!['text', 'image', 'audio'].includes(option?.kind)) {
+          throw new Error(`option ${index + 1}: kind must be text, image or audio`);
+        }
+        if (option.kind === 'text') return;
+        const url = attach(option.src);
+        if (!url) throw new Error(`option ${index + 1}: src must be an http(s) URL or an existing image/audio file`);
+        media.push({ index, url });
+      });
+      return { boardId: randomUUID().slice(0, 8), shown: true, media };
+    },
+  };
+
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? '/', base);
+    const cors = {
+      'access-control-allow-origin': '*',
+      'access-control-allow-headers': 'content-type',
+      'access-control-allow-methods': 'GET,POST,OPTIONS',
+      'cache-control': 'no-store',
+    };
+    const json = (code, body) => {
+      res.writeHead(code, { ...cors, 'content-type': 'application/json; charset=utf-8' });
+      res.end(JSON.stringify(body));
+    };
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, cors).end();
+      return;
+    }
+    if (req.method === 'GET' && url.pathname === '/status') {
+      json(200, { ok: true, port, media: media.size });
+      return;
+    }
+    if (req.method === 'GET' && url.pathname === '/settings') {
+      json(200, { values: loadSettings(), defaults: DEFAULT_SETTINGS, options: LANGUAGES });
+      return;
+    }
+    if (req.method === 'POST' && url.pathname === '/settings') {
+      let body = '';
+      req.on('data', (chunk) => { body += chunk; if (body.length > 4096) req.destroy(); });
+      req.on('end', () => {
+        try {
+          const parsed = body ? JSON.parse(body) : {};
+          json(200, { values: saveSettings(parsed), defaults: DEFAULT_SETTINGS });
+        } catch (error) {
+          json(400, { ok: false, error: String(error?.message ?? error) });
+        }
+      });
+      return;
+    }
+    if (req.method === 'GET' && url.pathname.startsWith('/media/')) {
+      const fileName = url.pathname.slice('/media/'.length);
+      const type = media.get(fileName) ?? TYPES[extname(fileName).toLowerCase()];
+      const file = join(mediaDir, fileName);
+      if (!type || !existsSync(file)) {
+        json(404, { ok: false, error: 'unknown media' });
+        return;
+      }
+      res.writeHead(200, { 'content-type': type, 'content-length': statSync(file).size, 'cache-control': 'no-store' });
+      createReadStream(file).pipe(res);
+      return;
+    }
+    if (req.method === 'POST' && url.pathname === '/attach') {
+      let body = '';
+      req.on('data', (chunk) => { body += chunk; if (body.length > 4096) req.destroy(); });
+      req.on('end', () => {
+        try {
+          const { path } = body ? JSON.parse(body) : {};
+          const attached = attach(path);
+          if (!attached) {
+            json(400, { ok: false, error: 'cannot attach this file' });
+            return;
+          }
+          json(200, { ok: true, url: attached });
+        } catch (error) {
+          json(400, { ok: false, error: String(error?.message ?? error) });
+        }
+      });
+      return;
+    }
+    json(404, { ok: false, error: 'not found' });
+  });
+
+  ctx.effect(() => {
+    const dispose = ctx.tools.register(tool);
+    return () => {
+      server.close?.();
+      dispose?.();
+    };
+  });
+  server.once('error', () => {});
+  server.listen(port, '127.0.0.1');
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Choice",
+    "description": "Pick one of several answers, images or sounds right in the chat"
+  }
+}

package/locale/ru.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Choice",
+    "description": "Выберите один из вариантов, картинок или звуков прямо в чате"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Choice",
+    "description": "在聊天中从多个答案、图片或声音里选择一个"
+  }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@machine202502/dsh-choice",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "type": "module",
+  "description": "Single-choice board in the chat: pick one of several answers, images or sounds with a click",
+  "license": "MIT",
+  "author": "machine202502",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "cordis.patch.yml",
+    "icon.svg",
+    "locale/*.json",
+    "README.md",
+    "README.ru.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "icon": "./icon.svg",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}