StackChan AI Server 2.8.0-beta.3

Changelog

2.8.0-beta.3 (Beta)

• Released the accumulated shared-server and standalone improvements below for the HA add-on. Added crown-and-wings artwork to the bundled settings header/favicon, HA store icon/logo and bilingual README headers.
• Fixed HA launcher handling of gemini_enable_tools: false and forwarded gemini_enable_search into the runtime configuration. Previously, false was replaced by the default and Search was omitted.
• Matched the Docker compiler/runtime Alpine versions at 3.23, made Go dependency resolution read-only at build time, and excluded local data, credentials, logs and packages from the Docker build context.
• Added a four-architecture container verification workflow that starts both the HA launcher and standalone Compose, checking settings/authentication, saved settings after restart, embedded artwork, and advertised NVS/OTA ports without live credentials.
• Added a permanent device setup / NVS guide to the shared HA and standalone settings UI, with runtime host/port, copyable OTA URL, USB/ESP-IDF instructions, and whole-NVS overwrite warnings. Setup metadata is authenticated in standalone and read-only; invalid or loopback targets do not produce a copyable URL.
• Kept settings API requests relative to the HA Ingress path and allowed same-origin embedding only in HA mode; standalone retains frame protection. Separated the HTTP listener address from the advertised device port so Docker custom host-port mappings work alongside native macOS ports.
• Added opt-in per-device local text history, bounded cross-session context for all provider paths, authenticated Markdown export/clear controls, and startup/hourly retention cleanup.
• Added a configurable silent follow-up timeout (15 seconds by default in standalone) that closes the audio channel so standard firmware returns to local wake-word/button standby; silent packets and automatic listen messages do not extend it.
• Combined Gemini transcription fragments per turn for history and stopped logging the full Gemini setup payload, which may now contain private past context.
• Added an optional standalone Home Assistant bridge: configure the HA URL and Long-Lived Access Token to let voice sessions discover entities, query state, call services, and run background HA tasks without routing device traffic through HA.
• Added the first macOS native standalone packaging path: an unsigned development DMG builder with bundled OPUS runtime, automatic LAN host/port selection, persistent per-user state, and local settings-page launch.
• Refreshed the standalone settings GUI with a responsive layout, sidebar navigation, runtime and configuration summary cards, grouped pipeline stages, and a persistent save bar without changing the settings API.
• Updated indirect golang.org/x/net and golang.org/x/text dependencies, plus the required golang.org/x/sys version and checksums, to address the reported dependency advisory.
• The NVS injector now accepts a resolvable LAN hostname as well as an IPv4 address for standalone OTA URLs; automatic service discovery is not enabled because it would require firmware support.
• Added the standalone settings GUI with separate OpenAI Realtime, Gemini Live, TokenHub, OpenRouter, and OpenAI-compatible provider entries.
• Added protected provider catalog discovery: model names are fetched from the configured Provider API, while native voice catalogs are populated for OpenAI and Gemini.
• Added clearer discovery errors and kept catalog checks separate from saving settings, so a failed check cannot overwrite the active configuration.
• Added standalone GUI controls for Gemini HA tools and Google Search, with the runtime now honoring those saved flags for new sessions.
• Fixed the standalone default so the Home Assistant-only Gemini tools setting starts disabled; added Gemini fields to the standalone environment example.
• Aligned the add-on OpenAI voice schema with the current GUI/provider voice catalog.
• Added a browser login page for the standalone settings UI; the token is exchanged for a short-lived HttpOnly session cookie.
• Disabled HA-only tools and background-task controls when standalone's optional HA bridge is off, while keeping Gemini Search available.
• Documented how to retrieve the generated settings token after detached Compose startup and how to use a custom settings host port.
• Added TokenHub and OpenRouter environment examples, plus custom-port support and regression coverage in the NVS OTA injector for same-host HA and standalone deployments.
• Kept standalone runtime mode read-only at the API and persistence layers, filtered settings responses to GUI fields, rejected unsupported updates, and serialized concurrent settings writes.
• Reject invalid device_profiles JSON in the settings API, and allow an explicitly cleared profile field to override older environment configuration.
• Reject unknown Provider values at the settings API instead of deferring the error until a device connects.
• Preserve standalone environment-configured Device-Id profiles when the settings UI is opened and an unrelated field is saved.
• Add no-store and browser security headers to the settings UI and API responses.
• Show actionable settings API validation errors in the standalone GUI instead of a generic save failure.
• Add a standalone-only logout link to the settings GUI.
• Show the active runtime mode in the settings GUI, including whether Home Assistant is connected or omitted.
• Document the standalone first-start defaults for Device-Id profiles, system prompt, and audio buffering.

Upgrade and testing notes

• HA: back up the add-on, refresh the add-on store, then update to 2.8.0-beta.3 and restart. Keep existing options and /data; open Web UI for the updated settings and permanent NVS guide. The built-in HA Configuration tab is a separate form. The store icon is not the navigation sidebar icon.
• Docker: fetch the updated source, preserve .env and the mounted data directory, then run docker compose -f docker-compose.standalone.yml up --build -d from stackchan-server. Containers are built from source; no prebuilt registry image is published. Existing containers do not update merely because GitHub changed.
• macOS: the independently versioned macos-v0.1.1 universal DMG remains the current download; this HA/container release does not replace that artifact.
• Automated tests do not replace physical StackChan audio, real HA Supervisor/Ingress or live AI-provider testing. Those end-to-end checks remain outstanding. The existing full-project vet warnings in internal/web_socket/web_socket.go are outside this release; the full Go suite is run with -vet=off, with a separate AI-package race check.

macOS 0.1.1 — Crown & Wings

StackChan AI Server for macOS 0.1.1 — Crown & Wings

更新内容 / Changes

• 恢复选定的手绘皇冠＋天使翅膀形象，保留接近实机的方形机身、点眼和直线嘴。

• DMG 中的应用图标、网页页头小图标、登录页和浏览器图标统一使用这一形象，处理透明外缘。

• 中英文 README 加入图片，补齐 Home Assistant 商店的 icon.png / logo.png。

• 本次只更新外观，不修改语音处理、设备接入或已保存的配置。

• Hardware-faithful StackChan artwork with a simple hand-drawn crown and angel wings,
  retaining the original dot eyes and straight mouth.

• Matching transparent artwork in the macOS app's full ICNS size set and the
  embedded settings header, login page and browser icon.

• Images in both READMEs and matching Home Assistant store icon/logo resources,
  with asset consistency and transparency regression checks.

• Visual-only update: voice processing, device setup and saved configuration are unchanged.

下载与升级 / Download and upgrade

下载 StackChan-AI-Server-0.1.1-macos-universal.dmg；无需自行构建或安装 Docker。
安装包包含 Apple Silicon 和 Intel 两种架构，构建目标为 macOS 12+，静态打包 OPUS。
升级前用“活动监视器”退出本应用的 stackchan-server 进程，再把新应用拖入“应用程序”替换。
设置与对话历史保留在原来的 Application Support 目录；不要同时运行两个副本。
旧版 0.1.0 安装包继续保留，便于回退。

Download the universal DMG from Assets. No user build or Docker installation is needed.
Apple Silicon and Intel executables target macOS 12+, with OPUS included statically.
Stop the old app's stackchan-server processes in Activity Monitor before replacing
the app in Applications. Existing settings/history are retained; do not run two copies.
The 0.1.0 download remains available. Verify the matching checksum before installing:

shasum -a 256 -c StackChan-AI-Server-0.1.1-macos-universal.dmg.sha256

限制与验证 / Limitations and verification

仍是临时签名预览版，尚无 Developer ID 签名或 Apple 公证，也没有菜单栏控制和自动更新。
确认来源后，无法验证开发者的提示可参考
Apple 安装说明；不要全局关闭 Gatekeeper 或绕过恶意软件警告。
HA 这次只更新仓库内的商店图片，不发布新插件版本；已安装插件内部的网页图片要等更新或重建后才改变。
商店图片不替代 HA 导航侧栏的图标。

Still an ad-hoc signed preview, not Developer ID signed or Apple notarized; no
menu-bar controls or automatic updates. Follow the Apple guidance above for
unidentified-developer warnings; never disable Gatekeeper globally or bypass malware warnings.
This does not publish a new HA add-on version. Store image files are updated in
the repository; an already installed add-on retains its bundled GUI image until
updated/rebuilt. Store artwork does not replace HA's navigation sidebar icon.

候选 DMG 已验证：校验、挂载、签名、两种架构与最低系统目标、完整应用图标、独立启动、
受保护的设置接口、设备 OTA 接口，以及桌面/手机网页图片显示。静态 OPUS 和图标测试在
两种架构通过，Intel 使用 Rosetta。Go 测试、构建、Python 测试与 shell/YAML 检查通过。
未测试真实 HA 商店画面、物理 StackChan、外部 AI 服务、macOS 12 实机或真实 Intel Mac。
已有两处非本次引入的日志格式 vet 警告仍在 internal/web_socket/web_socket.go。

Candidate DMG integrity, mount, signatures, both architectures/minimum target,
complete ICNS set, isolated startup, protected settings, OTA and desktop/mobile
image rendering were verified. Static OPUS and icon tests passed for both
architectures (Intel via Rosetta). Go tests/build, Python tests and shell/YAML
checks passed. Actual HA store rendering, physical StackChan, external AI services,
macOS 12 and physical Intel hardware were not tested. Two pre-existing logging
format vet warnings remain in internal/web_socket/web_socket.go.

macOS 0.1.0 — Universal DMG Preview

StackChan AI Server for macOS 0.1.0 — Preview

下载即用 / Ready to run

下载 Assets 中的 StackChan-AI-Server-0.1.0-macos-universal.dmg，
将应用拖入“应用程序”后打开。不需要自行构建，也不需要 Docker、Go、Homebrew 或音频库。
安装包包含 Apple Silicon 和 Intel 两种架构，构建目标为 macOS 12+。
同时提供匹配的 .sha256 校验文件。

Download the universal DMG from Assets, drag the app into Applications, and launch.
No user build or extra runtime installation is needed. Both Apple Silicon and
Intel executables are included, targeting macOS 12+. A matching checksum is attached.

更新内容 / Included

• 可直接下载的通用 DMG，静态打包 OPUS，并附开源许可和校验文件。

• 新的 3D StackChan 应用图标；网页页头、登录页和浏览器图标使用同一形象。

• 当前 standalone 设置界面、可选 HA 实体控制桥接、本地文字历史、静默待机和常驻 NVS 注入指引。

• 中英文安装及升级说明；首次启动显示设置页登录 Token。

• Ready-made universal DMG with statically included OPUS, license notices and SHA-256 checksum.

• A 3D StackChan app icon, shared with the settings header, login and browser icon.

• Current standalone provider settings, optional HA bridge, text history, idle standby and NVS setup guide.

• Bilingual installation/upgrade instructions and a first-run settings-token dialog.

安装与限制 / Installation and limitations

这是临时签名的预览版，尚无 Developer ID 签名和 Apple 公证。
确认下载来自本项目后，如遇无法验证开发者的提示，可按
Apple 官方说明在“系统设置 → 隐私与安全性”中选择“仍要打开”。
不要关闭整个系统的 Gatekeeper，也不要绕过恶意软件警告。

预览版尚无菜单栏控制或自动升级。升级前在“活动监视器”中停止本应用的
stackchan-server 进程，再替换应用；不要同时运行多个副本。
数据保留在 ~/Library/Application Support/StackChan AI Server，删除应用不会清除数据。
设备仍需按 NVS 指引配置；注入会覆盖原 NVS，可能需要重新配网。
设置页只监听本机；如需设备接入，请在 macOS 防火墙提示时允许本应用的局域网传入连接。

This preview is ad-hoc signed, not Developer ID signed or Apple notarized.
After verifying the source, use Privacy & Security → Open Anyway for an
unidentified-developer warning. Do not disable Gatekeeper globally or bypass malware warnings.
There are no menu-bar controls or automatic updates yet. Stop this app's
stackchan-server processes in Activity Monitor before replacing it; do not run
multiple copies. Settings/history remain in the per-user Application Support
directory. Configure the device via the NVS guide; injection replaces existing NVS.
The settings page is local-only; permit incoming LAN connections if prompted and needed.

此 Release 只发布 macOS standalone 安装包，不修改 HA add-on 版本。
This is a standalone macOS release, not a new HA add-on release.

验证范围 / Verification scope

已在 Apple Silicon / macOS 26.6.2 上验证候选 DMG 的校验、挂载、签名完整性、
应用启动、设置页与设备 OTA 接口；两种架构的静态 OPUS 编解码测试均通过，
Intel 路径使用 Rosetta 执行。桌面和手机尺寸网页的图标加载及鉴权回归通过。
尚未在 macOS 12 或真实 Intel Mac 上实机测试，也未验证真实设备语音及外部 AI / HA 服务。

Candidate DMG integrity, mount, signature sealing, app startup, settings and OTA
endpoints were checked on Apple Silicon / macOS 26.6.2. Static OPUS codec tests
passed for both architectures, with Intel execution under Rosetta. Desktop/mobile
GUI image loading and authentication regressions passed. macOS 12, physical Intel
hardware, real device audio and external AI/HA sessions have not been tested.

v2.8.0-beta.2 — Realtime API and Model Inputs

What changed

• Updated OpenAI Realtime sessions to the current GA audio.input and audio.output schema, fixing the session.input_audio_format API error reported in #9.
• Resampled 16 kHz StackChan input audio to the 24 kHz PCM format required by OpenAI Realtime and handled the current output audio and transcript event names.
• Changed OpenAI Realtime and Gemini Live model settings from fixed lists to free-text fields, addressing #10 and allowing new model IDs without another add-on release.
• Updated the default OpenAI Realtime model to the stable gpt-realtime alias.
• Added regression tests for the Realtime session payload and audio resampling.

Verification

• AI package unit tests: passed
• AI package race tests: passed
• Full Go test suite: passed
• AI package vet: passed
• Full Go build: passed
• Shell syntax, YAML parsing, and diff checks: passed

Known limitation

A live OpenAI API session and physical StackChan audio test were not run because no API key or device was available in the workspace.

v2.8.0-beta.1 — Background Tasks Beta

What changed

• Added per-device background task queues for OpenAI Realtime conversations, with create, status, and cancellation tools.
• Persisted task state and pending announcements across device reconnects, with explicit restart failure recovery and result expiry.
• Delayed completion announcements until the user, model response, and device audio queue are idle, and prevented duplicate delivery.
• Added Home Assistant Ingress settings for an OpenAI-compatible background Agent endpoint, model, timeout, and prompt.
• Added FIFO, cancellation, owner-isolation, reconnect, restart, expiry, and race tests for background task lifecycle behavior.

Beta testing notes

• Enable the feature from Open Web UI → Background tasks and configure an OpenAI-compatible model that supports /v1/chat/completions.
• Background task tools are currently available only when the foreground provider is OpenAI Realtime; Gemini Live and the turn-based compatible voice pipeline are not included in this beta.
• Web search and code execution are not added automatically. The background model can use the existing Home Assistant tools.
• Tasks interrupted by an add-on restart are reported as failed; completed results waiting for announcement are retained for up to seven days.
• This release passed automated unit, race, vet, build, shell, and YAML checks. Physical StackChan and live Home Assistant testing is requested from beta testers.

Suggested physical test

Start a task that takes about 60 seconds, continue at least three voice turns while it runs, interrupt the first result announcement, reconnect, and confirm that the result is announced exactly once afterward.