Skip to content

Your lightweight open-source personal agent.

chore(release): prepare 0.4.0

Xubin Renf93e92618231
diff --git a/docs/releases/0.4.0.md b/docs/releases/0.4.0.md
new file mode 100644
index 000000000..8e1198238
--- /dev/null
+++ b/docs/releases/0.4.0.md
@@ -0,0 +1,67 @@
+# nanobot 0.4.0 — release notes draft
+
+This release is being prepared; it has not been published. These notes cover changes already merged since v0.3.5. Final candidate checks, package acceptance and maintainer approval are still required. Do not use an unreleased version number as an installation instruction.
+
+## Highlights
+
+### Updates with explicit confirmation and recovery
+
+Settings → About brings stable and opt-in Preview updates into one flow. Supported official-installer and POSIX uv environments can review an exact version, confirm installation and restart, and reconnect to the updated gateway. Other installation methods receive instructions for their original package manager or deployment owner.
+
+Installer-managed environments can repair a failed installation and, when safe, restore the original program. Recovery does not overwrite current configuration or conversations with an old backup. Package verification, stopped writers and protected-data checks remain required; automatic recovery does not cover every interruption or installation method. Public in-app installation additionally depends on the signed release and complete public update assets, not just this code being merged. See [Updating nanobot](../updating.md).
+
+### One durable store for conversation history
+
+The gateway now owns model history and WebUI display history in SQLite. Existing JSONL conversations and display segments are imported on startup, with retained source backups. History loading, live output reconciliation, queued follow-ups and `/goal` continuation have received reliability fixes. Model text already streamed before a connection failure is retained for subsequent context without changing the failed request into a success.
+
+### A more usable workbench
+
+- Connect the WebUI to existing remote nanobot instances, with explicit host identity, pairing and connection recovery.
+- Navigate complete prompt history with bounded loading, search loaded message text and session handles, rename topics inline, and archive topics in batches.
+- Keep delegated tasks and their details within reach, with shared sidebar/Composer run state and clearer retry and completion feedback.
+- Use local-file and video attachments, image thumbnails, file cards, and Markdown previews with a source view. Arbitrary website embedding has been removed; external links open in the browser.
+- Adjust reading sizes, use smoother theme transitions, and work with improved mobile layouts and touch interactions.
+- Run literal shell commands from the Composer with the existing permission boundary; command output remains distinguishable from an agent reply.
+
+### Terminal, models and integrations
+
+- Native terminal packages include Mermaid image rendering and smaller standalone builds with target-specific native dependencies. Platform wheels include the matching TUI and built WebUI; supported wheel installations do not need Bun or a first-launch TUI download.
+- Model setup includes searchable providers, explicit API choices and per-preset request overrides. Shared proxy settings can be selected independently by supported providers, web tools and MCP connections.
+- Native Linear and WhatsApp Agent Platform channels, QQ QR setup, DeepSeek Search, and further provider/channel compatibility improvements are included.
+- Scheduled jobs can be updated, enabled and disabled in place, and their recent run history can be inspected. Restart and delivery fixes preserve pending work without treating an unknown delivery result as permission to replay it.
+
+## Before upgrading from v0.3.5
+
+1. Use the original installation method on the gateway computer, under its original OS account. v0.3.5 does not contain this new in-app updater; the first upgrade must use the installer, package manager or deployment's existing route. Existing environments are not silently converted into official-installer environments.
+2. Finish active work and stop every nanobot process sharing the environment or data. Back up the entire selected configuration directory and workspace together while writers are stopped, including authentication, session data and WebUI state. Do not copy only a live SQLite database file.
+3. After publication, select the final 0.4.0 package through the [installation-owner instructions](../updating.md#installation-owners), preserving extras, constraints and custom options. Containers must keep their existing data volumes; do not install packages into a running container as an upgrade strategy.
+4. Start the same instance through its original launcher. Confirm the running version in Settings → About, open older conversations, send a new message and check that the saved state remains available after another restart. An installer exit code alone does not verify the running gateway.
+5. Reconnect or reload clients after the gateway upgrade. For remote use, update the intended gateway rather than the browser computer, and follow any client/host compatibility guidance shown by the application.
+
+### Data and configuration compatibility
+
+JSONL import remains supported throughout 0.4.x. Installations with only legacy JSONL data must pass through an import-capable release before 0.5.0. Imported source files are retained as backups; do not delete the old WebUI directory, which also holds preferences. A corrupt or ambiguous import stops startup with an actionable error instead of silently skipping history. See [Session Storage](../cli-reference.md#session-storage).
+
+Older versions cannot read newly saved SQLite display history. A downgrade is not an in-place recovery shortcut: stop all writers and follow the documented pre-upgrade-backup restoration procedure, explicitly accounting for newer messages that the old backup does not contain. The managed updater never performs this data rollback automatically.
+
+Legacy proxy configuration migration remains supported in 0.4.x. Review the migrated shared proxy and per-service choices before saving; a browser's proxy settings are separate from the gateway's. See [Configuration](../configuration.md).
+
+v0.4.0 is the first stable release with the temporary OpenAI `apiType` / `api_type` → `api` migration. It remains supported for the immediately following release; its exact tag must be recorded when that release is allocated. Save configurations in the current `api` format during this window. The third release containing this change will no longer accept the old selector. This is a separate compatibility window from the 0.4.x JSONL/proxy window. See [API selector migration](../configuration.md#legacy-openai-api-selector-migration).
+
+### Installation and platform boundaries
+
+Fresh official-installer environments use a dedicated venv and launch the normal WebUI persistently in the background. Existing unrecorded installs retain their original lifecycle. Use the same instance selectors with `nanobot gateway stop` to stop a persistent instance; closing its terminal or browser does not stop it. On a local macOS desktop the WebUI can show a Dock icon; `--no-dock` suppresses it. See [WebUI](../cli-reference.md#webui).
+
+Python 3.11+ remains required. Native wheels target macOS 13+ (arm64/x64), glibc 2.17+ Linux (arm64/x64) and Windows x64; x64 requires SSE4.2. There is no native wheel for Windows ARM64 or musl Linux. Classic Python and WebUI routes remain distinct from native TUI support. Cross-built packages are not proof of native execution on every platform.
+
+Preview remains off by default. Selecting a channel is not permission to install, stop tasks or restart a gateway. Turning Preview off does not downgrade a newer installed version. A missing or unverifiable public release must not be offered as a successful automatic install.
+
+## Release scope and remaining checks
+
+These notes describe the current preparation base, not open PRs or a promise that all known issues are fixed. In particular, preventing new `/goal` event-sequence collisions does not repair already conflicting legacy history. The separate Dock window-reuse work is not included in this preparation base. Reconcile these limitations with the final merged range before publishing.
+
+The release PR tracks the final CI/review, package hashes, native installation and upgrade/recovery matrix, historical-baseline coverage, source-offer commitment and documentation handoff. The [release checklist](../releasing.md) remains authoritative. Merge preparation before creating a tag, then compare the merged sources with the accepted candidate and reverify any changes. Tag that exact verified commit, not a later untested `main` tip. No tag, GitHub Release, PyPI upload, signing switch, update-feed advancement or website deployment is performed by this preparation PR.
+
+## Acknowledgements and changelog
+
+Thank you to everyone who reported issues, supplied reproductions, tested changes and contributed fixes. The immutable [preparation-base changelog](https://github.com/HKUDS/nanobot/compare/v0.3.5...b07b3eac244ff7faa7eeb2d4777fe54dbae1b6d2) records the included changes and their authors. Replace this draft's base comparison with the final release comparison and reconcile contributor acknowledgements before publication; commit counts must not be described as merged-PR counts.
diff --git a/nanobot/__init__.py b/nanobot/__init__.py
index d562b7902..70478e868 100644
--- a/nanobot/__init__.py
+++ b/nanobot/__init__.py
@@ -49,7 +49,7 @@ def _resolve_version() -> str:
return _pkg_version("nanobot-ai")
except PackageNotFoundError:
# Source checkouts often import nanobot without installed dist-info.
- return _read_pyproject_version() or "0.3.5"
+ return _read_pyproject_version() or "0.4.0"
__version__ = _resolve_version()
diff --git a/pyproject.toml b/pyproject.toml
index 53c266276..da7995603 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "nanobot-ai"
-version = "0.3.5"
+version = "0.4.0"
description = "A lightweight personal AI assistant framework"
readme = { file = "README.md", content-type = "text/markdown" }
requires-python = ">=3.11"