Repository navigation
Releases
v0.4.5 - Decoupled Constants & Prompts, Multimodal Attachments, and Unified SSOT
What's Changed in HostSpark v0.4.5
A major architectural decoupling and feature release introducing a centralized Single-Source-of-Truth (SSOT) architecture for operational constants and AI prompts, full-spectrum multimodal attachment handling (audio, voice notes, video, documents, and images) with safe extension validation and MIME auto-extension derivation, and seamless backward compatibility.
🧱 Architectural Decoupling: SSOT Constants & Centralized Prompts
src/hostspark/constants.py:- Eliminated scattered magic numbers across all modules.
- Centralized network & process timeouts (
DEFAULT_SUBPROCESS_TIMEOUT_SECONDS,PTY_COMMAND_TIMEOUT_SECONDS,SSRF_MEDIA_DOWNLOAD_TIMEOUT_SECONDS). - Centralized circuit-breaker thresholds (
DEFAULT_CIRCUIT_BREAKER_MAX_FAILURES = 3). - Unified message & prompt length limits (
MAX_MESSAGE_CHUNK_CHARS,LONG_MESSAGE_FILE_THRESHOLD_CHARS,SCHEDULE_MAX_ORIGINAL_PROMPT_CHARS,SCHEDULE_MAX_EXPANSION_PROMPT_CHARS). - Consolidated safe extension sets (
AUDIO_EXTENSIONS,VIDEO_EXTENSIONS,IMAGE_EXTENSIONS,DOC_EXTENSIONS,SAFE_EXTENSIONS).
src/hostspark/prompts.py:- Centralized all system prompts, multimodal analysis constraints, and dynamic prompt builders into one clean module.
- Dedicated builders:
build_attachment_prompt(),build_learn_prompt(),compose_followup_prompt(),compose_agy_prompt(), andbuild_prompt_expansion_request(). - Zero hardcoded prompt strings in message dispatchers, scheduler handlers, or query callbacks.
🎙️ Full-Spectrum Multimodal Attachments & Audio/Video Ingestion
- Audio & Voice Note Handling:
- Telegram Voice notes (
.ogg) and Audio uploads (.m4a,.mp3,.wav,.ogg,.flac,.aac) are natively received and stored in per-chatuploads/directories. - MIME-based Auto-Extension: Audio files uploaded without file extensions dynamically derive their correct suffix based on Telegram MIME types instead of being forced into
.m4a.
- Telegram Voice notes (
- Video & Document Ingestion:
- Direct upload support for vid
8000
eos (
.mp4,.mov,.mkv) and documents (.pdf,.txt,.py,.json,.csv,.md, etc.).
- Direct upload support for vid
8000
eos (
- Strict Safe Whitelisting:
- Any uploaded file whose extension is not in
SAFE_EXTENSIONSis safely rejected with an informative list of supported formats, preventing arbitrary or hazardous file staging.
- Any uploaded file whose extension is not in
- Native Gemini Multimodal Guidance:
- Dispatches attachments to AGY with explicit multimodal prompts guiding Gemini's native visual, video, and audio speech recognition (ASR) capabilities without running heavy local transcription models.
🔄 Backward Compatibility & Clean Linter Re-exports
- Preserved full backward compatibility for legacy imports from
hostspark.core.prompt,hostspark.telegram.media, andhostspark.storage.schedule_store. - Declared explicit
__all__lists in re-exporting modules, guaranteeing zero unused-import (F401) warnings in static analysis tools (pyflakes,flake8).
🛠️ Circuit-Breaker UI & Schedule Handler Synchronization
- Replaced hardcoded thresholds in
scheduler/handlers.pywithDEFAULT_CIRCUIT_BREAKER_MAX_FAILURES. /schedule_listand/schedule_shownow automatically reflect the true circuit-breaker state without desynchronization risks.
📦 Installation & Observability Enhancements
install.sh:- Replaced silent error swallowing (
|| true) with proactive detection and actionable warnings for system-leveledge-ttsandpillowinstallations. - Added documentation explaining why system Python is targeted for AGY standalone binary execution.
- Replaced silent error swallowing (
📖 Documentation Updates
- Updated
README.mdandREADME.zh-TW.md:- Added architectural decoupling and unified constants in Key Features.
- Added
/tokens,/compact, and/learncommands to the Telegram command reference table. - Expanded multimedia tool prerequisites and automatic installer details.
🧪 Test Suite & Health Metrics
- Expanded test suite to 140 unit and integration tests (100% passing, 0 regressions):
- 125 baseline tests.
- +2 media resolver & multimodal path detection tests (
test_media_resolver.py). - +7 prompts & constants integrity tests (
test_prompts.py). - +6 attachment handling & safe extension tests (
test_attachments.py).
- Full static analysis: 0 errors/warnings on
pyflakes.
📦 Upgrade Notes
To upgrade an existing HostSpark installation to v0.4.5:
git pull origin main
sudo systemctl restart agy-telegram.serviceHostSpark v0.4.4
What's Changed in HostSpark v0.4.4
A dedicated user experience (UX) and stability release introducing live heartbeat elapsed timers, one-click /cancel self-rescue hints, stall warning detection for slow subcommands, nested coroutine variable scope fixes, and anti-blocking timeout optimizations.
⚡ Live Dynamic Heartbeat Elapsed Timer & Zero-Freeze UX
- Real-Time Heartbeat Timer: Status messages in Telegram now actively refresh with an elapsed time counter (
⏳ 國網AI助理 正在思考與執行中,請稍候... (已耗時 14s)). - Eliminates Screen Freezing: Even if an underlying tool or subcommand takes time or produces no intermediate output, the timer ticks every ~3–4 seconds, reassuring users that the session is alive and actively progressing.
- Auto-Elapsed in Progress Updates: When new streaming output or tool execution reports arrive, the elapsed time is smoothly preserved and shown alongside current tool status.
🛡️ One-Click Emergency /cancel Self-Rescue
- Clickable Status Card Hint: Added
👉 可點擊 /cancel 隨時中斷任務directly to the live progress card. - Instant Abort: Users can simply tap the command link on mobile or desktop to cancel runaway or stuck tasks immediately without having to recall or manually type slash commands.
⚠️ Stall Warning Detection (>30s)
- Proactive Stall Alerts: If a subcommand runs for over 30 seconds without generating stdout/stderr (e.g. streaming log readers, heavy compilation, or network waits), the status message automatically displays:
⚠️ 底層指令執行中,已超過 35s 未有新輸出... - Keeps users informed about long-running operations before any timeout triggers.
🐛 Bug Fix: keep_typing Coroutine Scope Fix
- Fixed
UnboundLocalError: Addednonlocal last_edit_timeto the nestedkeep_typing()coroutine insidesrc/hostspark/telegram/dispatcher.py. - Previously, assigning to
last_edit_timewithin the inner coroutine withoutnonlocalcaused Python to treat it as an unbound local variable, silently terminating the typing heartbeat loop.
⏱️ Timeout & Anti-Blocking Prompt Optimizations
- Optimized Default Timeout: Adjusted default
AGY_TIMEOUT_SECONDSfrom 600s (10 minutes) to 180s (3 minutes) in.env.exampleand documentation, preventing excessive waiting periods if a task stalls. - Anti-Blocking Rule Prompt: Updated prompt recommendations in
.env.exampleadvising the assistant to:- Never read continuous stdout streams without finite limits (e.g.
head /var/log/apache2/access.login Docker containers whose stdout pipes never reach EOF). Always usedocker logs --tail Nor strict timeouts (timeout 5s ...). - Background daemon processes immediately.
- Never read continuous stdout streams without finite limits (e.g.
📖 Documentation Updates
- Updated
README.mdandREADME.zh-TW.mdto detail:- Active heartbeat timer and stall warnings in feature highlights.
/cancelprogress card integration.- Default
AGY_TIMEOUT_SECONDS=180.
📦 Upgrade Notes
To upgrade an existing HostSpark installation to v0.4.4:
git pull origin main
sudo systemctl restart agy-telegram.serviceHostSpark v0.4.3
What's Changed in HostSpark v0.4.3
A stability and capability release bundling our official Web Service Deployment & Cloudflare Tunnel Skill, introducing Docker-based persistent tunnel management to eliminate Error 1033, auto-syncing skills on install, fixing a markdown link crash in media detection, and refining streaming verbosity configuration.
🚀 Bundled web-service-deployer Skill & Persistent Docker Tunnel
- Out-of-the-Box Server Deployment Skill: Added
skills/web-service-deployer/SKILL.mddirectly into the repository. Teaches the AI assistant to safely deploy web apps (Vite, React, Vue, Flask, FastAPI, Express, Docker) without terminal blocking. - Docker Persistent Tunnel Architecture (Eliminates Error 1033): Addressed the critical issue where host-level
nohuptunnels are terminated by the agent environment's process reaper when awaiting user input or on context reset. Promoted Docker containerization (cloudflare/cloudflared:latestwith--restart unless-stopped) as the golden standard for both container networks and host port proxying (--net=host). - Zero-Blocking Architecture: Enforces background detachment to prevent headless Telegram bot sessions from locking up when running dev servers.
- Instant Mobile Previews via Cloudflare Quick Tunnel: AI automatically provisions
*.trycloudflare.comtunnels for zero-config public HTTPS testing on mobile devices. - Error 1033 Troubleshooting & Lifecycle Documentation: Added diagnostic instructions for Cloudflare Tunnel
Error 1033(daemon disconnected/terminated) and explained the ephemeral lifecycle of quick tunnels along with Anycast PoP routing (location=hkg09/location=tpe01). - Automatic Skill Sync: Updated
install.shto automatically install all bundled skills into~/.gemini/config/skills/on initial setup or upgrade.
🐛 Bug Fixes & Stability
- Media Link Parsing: Hardened URL extraction regex and added safety wrappers around
urlparseto prevent handler crashes on complex markdown links with query parameters or relative paths (2167a68).
⚙️ Configuration & Documentation
- Streaming Verbosity (
AGY_VERBOSE): DocumentedAGY_VERBOSEin.env.exampleandREADME.md(detailedfor full thinking traces,compactfor single-line summaries,silentto disable). - Progress Reporting Alignment: Clarified valid values for
AGY_PROGRESS_MODE(full,compact,delete). - Rule Prompt Recommendations: Added daemon backgrounding guidance to the default
AGY_RULE_PROMPT.
📦 Upgrade Notes
To upgrade an existing HostSpark installation to v0.4.3:
git pull origin main
./install.shThe install script will automatically sync the bundled skills to your global AGY configuration and restart the service.
HostSpark v0.4.2
HostSpark v0.4.2
A feature release adding per-chat project directories, simplified model/effort
selection, and a fix for /cancel (and every other command) being blocked while
a task is running. All 124 tests pass.
New: named project directories via /new [name]
Every chat previously ran agy f
8000
rom an anonymous, auto-assigned
workspaces/chat-{chat_id} folder with no way to see or choose it, and /new
only reset the conversation.
/new <name>creates-or-selects a single-segment directory under
AGY_WORKSPACE_ROOT(confined via a newvalidate_project_dir_name()
allowlist plus the existingsafe_join()path-traversal guard) and uses it
as the chat's working directory going forward, replacing the anonymous
folder. Picking a project also starts a fresh conversation./newwith no argument lists existing project directories as buttons
(current one checkmarked), mirroring the/modelpicker. The button
callback validates the name too, not just the typed-argument path./clearis decoupled from/newand keeps the old "just reset the
conversation, keep the working directory" behavior.- Switching to a genuinely different project directory also clears any
/add_direntries from the previous one -- those are absolute paths with
no per-project scoping and would otherwise silently keep granting agy
access to a now-unrelated project. - Chats that never call
/neware completely unaffected. - New
.envvars:AGY_DEFAULT_PROJECT_DIR(pre-seeds one directory, default
initial, so the picker isn't empty on a fresh install).AGY_WORKSPACE_ROOT
is reused as the parent directory/newis confined to.
Two bugs were found and fixed while building this, both confirmed by tracing
a real conversation transcript and testing the agy binary directly:
- agy doesn't recognize a directory as its "Active Workspace" just because
the subprocesscwdpoints at it -- without--add-dir <dir>it silently
falls back to its own internal scratch location
(~/.gemini/antigravity-cli/scratch) regardless ofcwd.run_agy()now
always passes--add-dirfor whatever directory it resolves. /newand/clearweren't actually starting a fresh agy session.
HostSpark never persisted aconversation_idback from agy's replies, so it
was alreadyNoneon every ordinary turn -- meaning every message fell
through to the--continuebranch regardless of what/new//clearhad
just reset, silently resuming agy's own last session from whatever
directory that was. Fixed with a one-shot in-memory marker that suppresses
--continue/--conversationfor exactly the next turn after a switch or
/clear, kept deliberately separate from the pre-existing, sticky
/new_project on|offtoggle so that manual setting can't be broken by it
(caught by a dedicated regression test before shipping).
New: simplified model + effort selection
/modelused to list every model x effort combination as separate
suffixed buttons (gemini-3.8-flash-high,-medium,-low, ...). It now
lists just the 3 base model names, with/effort(now with its own
low/medium/high inline picker, not just a typed argument) controlling
reasoning depth independently.- These base names have no unsuffixed form in agy's own model catalog, so a
newresolve_model_and_effort_args()recombines them into the real
--modelvalue agy expects (e.g.gemini-3.8-flash+medium->
--model gemini-3.8-flash-medium) instead of sending--model/--effort
separately, which agy rejects as conflicting. - Both pickers mark the chat's current selection with a checkmark, including
normalizing legacy stored values from before this change.
New: reorganized quick-action keyboard (3-3-2 layout)
[ /status ] [ /model ] [ /effort ]
[ /session ] [ /new ] [ /clear ]
[ /schedule_list ] [ /cancel ]
Fixed: /cancel (and everything else) could be blocked for a task's entire duration
python-telegram-bot processes one update at a time by default, and the
message handler blocked on the job's completion after enqueueing it. Sending
/cancel while a long task was running would sit undelivered until that task
finished on its own -- by which point there was nothing left to cancel.
Enabled concurrent_updates and stopped the handler from blocking; the queue
worker already reports back via the status message on its own.
Security
AGY_WORKSPACE_ROOT/AGY_WORKDIR previously defaulted to the entire home
directory when left blank, which is also the boundary used for attachment
uploads, /add_dir, and auto-detected output media. If you haven't already,
point both at a dedicated directory (e.g. /home/ubuntu/projects) rather
than leaving them blank.
Upgrade notes
chat_state.dbgains aworkspace_dircolumn via an idempotent migration
that runs automatically on startup (guarded by aPRAGMA table_info
check, so it's safe to restart repeatedly). Verified against a snapshot of
a live database before release; back upchat_state.dbbefore upgrading
as a precaution regardless.- Re-run
./install.shto pick up the new package version and restart the
service. - If
AGY_WORKSPACE_ROOT/AGY_WORKDIRare still blank in your.env,
create a dedicated directory and set both before relying on/new--
the target directory must already exist or the service will fail to start. - Existing chats keep using their old anonymous working directory until they
run/newthemselves; nothing is migrated automatically.
HostSpark v0.4.1
HostSpark v0.4.1
A patch release fixing three regressions discovered while deploying v0.4
to the live systemd service. All 107 tests still pass; no command or
config surface changed.
Fixes:
- .env was never actually loaded in the new src/hostspark package -- the
old bot.py called load_dotenv() at import time, but that call didn't
make it into hostspark.cli during the refactor, so TELEGRAM_BOT_TOKEN
and everything else in .env was invisible to the process outside of a
shell that happened to already export it. This is what took the live
service down after v0.4 was deployed. - logging.basicConfig was also dropped during the refactor, so every
logger.info() call (startup, scheduler loop, job execution, etc.) was
silently swallowed -- a real loss of visibility into a 24/7 unattended
service normally watched via journalctl. Restored. - Restoring INFO-level logging surfaced a pre-existing issue that
predates this refactor (confirmed present in v0.3 too): httpx logs the
full request URL at INFO level, and python-telegram-bot embeds the bot
token directly in that URL, so every Telegram API call was printing
the live token in plaintext to the systemd journal. httpx's logger is
now pinned to WARNING to stop this.
If your bot token was ever exposed via journalctl on a deployment
running the affected code, treat it as compromised and rotate it via
@Botfather's /token command.
Upgrade notes:
- Re-run
./install.shto pick up the new package version and restart
the service - If you rotate your token per the note above, update TELEGRAM_BOT_TOKEN
in .env before restarting
HostSpark v0.4
HostSpark v0.4
A structural refactor: the codebase moves from 12 flat root-level modules
(bot.py alone was over 2,000 lines) into a proper src/hostspark/ package,
plus new security tooling and CI fixes. No user-facing bot behavior
changes -- all 107 existing tests pass unchanged in intent, and every
Telegram command from v0.3 is preserved.
Highlights:
- Full package restructure into src/hostspark/: config, state, core
(executor/prompt/sanitizer/cli_args/pty/streaming), storage (chat_state/
conversation_db/schedule_store), telegram (app/formatters/media/auth/
dispatcher/handlers), and runtime (job_queue/instance_lock/
pending_actions/scheduler) - Standard packaging via pyproject.toml:
pip install -e .gives both a
hostsparkconsole script andpython -m hostspark; install.sh and the
generated systemd unit now launch the package instead of a flat script - bot.py kept as a thin backward-compatible launcher (sys.path bootstrap
into src/, delegates to hostspark.cli.main) for anyone still invoking it
directly - Centralized runtime state (CONFIG/SCHEDULE_STORE/CHAT_STATE_STORE/...)
into hostspark.state as the single source of truth, and migrated the
test suite to patch it directly instead of monkey-patching module
globals on the old flat bot.py - New security-scan.sh: pip-audit, bandit, semgrep, and gitleaks in a
self-contained tool venv, writing timestamped reports to
security-reports/ (gitignored) - security-scan.sh now also installs a gitleaks pre-commit hook that
blocks any commit whose staged changes contain a secret, instead of
relying solely on a later manual scan - Fixed CI (.github/workflows/ci.yml), which still referenced the
pre-refactor flat file layout and never installed the package itself;
also pinned actions/checkout and actions/setup-python to commit SHAs
instead of mutable version tags - Repo hygiene: removed an unrelated local AI-skill directory (.agents/)
that had been accidentally committed, and cross-linked README's Quick
Install section with INSTALL_BY_AI.md for AI-agent-assisted installs
Upgrade notes:
- Existing systemd deployments should re-run
./install.shto pick up
the new package install step and regenerated ExecStart
(python -m hostspark) - No .env changes required
v0.3: Multi-User Support, Per-Chat Isolation & Security Hardening
Highlights
- Multi-user & per-chat isolation: multi-user/chat authorization (
ALLOWED_USER_IDS,ALLOWED_CHAT_IDS), independent per-chat model/effort/mode/sandbox/verbose settings, and a dedicated AGY working directory per chat — fixing a real cross-chat conversation leak where--continuecould silently resume a different chat's conversation. - Live streaming & CLI passthrough: streamed AGY progress, PTY-fallback quota/context queries (
/usage,/quota,/context), and/agyCLI passthrough with two-phase confirmation for dangerous commands. - Scheduling & job queue: deterministic natural-language schedule-intent detection (routes straight into
/schedule_addinstead of blocking the job queue), a global job queue with auto-interrupt merging and crash recovery, and multi-admin broadcast for scheduled-task results and circuit-breaker warnings. - Security & stability hardening: SSRF-guarded output-media forwarding, fixed
--model/--effortconflicts, a/statusHTML-escaping bug,/restart//updatenow correctly triggers systemd'sRestart=on-failure, PID lock file permissions, and a daily cleanup pass for uploads/working directories older than 30 days. - One-shot context injection so a normal follow-up question can reference the result of a preceding
/usageor/contextquery. - Removed
/resume,/sessions, and the/continuebrowsing mode — AGY's own conversation metadata isn't reliably filterable per-chat, and per-chat workdir isolation already makes plain continuation reliable. - Docs: retired
class.md(folded intoSECURITY.md);install.shtranslated to English;README.md/INSTALL_BY_AI.mdare now English by default with linkedREADME.zh-TW.md/INSTALL_BY_AI.zh-TW.mdTraditional Chinese counterparts.
v0.2: Host-level Persistent Scheduling, Workspace Isolation & Customizable Waiting Messages
🚀 What's New in v0.2
💬 自訂等待提示(Customizable Waiting Message)
- 支援透過
.env中的AGY_WAITING_MESSAGE自訂機器人執行中的等待提示訊息。 - 預設提示內容調整為:
⏳ 國網AI助理 正在思考與執行中,請稍候...
⏰ 主機級持久定時排程(Persistent Scheduled Tasks)
- 支援
/schedule_add、/schedule_list、/schedule_show、/schedule_pause、/schedule_resume、/schedule_delete指令。 - 排程狀態由 SQLite(WAL 模式)持久化儲存,重開機與服務重啟後不會遺失。
- 具備連續 3 次失敗自動暫停保護(Circuit Breaker)與
[NO_REPORT]靜默檢查機制。 - 排程間隔下限可彈性調整至 1 分鐘,可透過
AGY_SCHEDULE_MIN_INTERVAL_MINUTES設定。
🛡️ 安全性與工作區隔離(Workspace Isolation & Security)
/schedule_add自動建構 Prompt 時採用獨立隔離工作區,不開放高風險權限。- 完善 Safe 與 Full 權限模式防護,以及日誌敏感資訊脫敏(Token / 密鑰 Redaction)。
📚 文件與教學
- 新增深度技術架構與維運教學手冊(
class.md)。 - 完善繁體中文指令手冊與維運 SOP。
v0.1: Antigravity CLI Telegram Bridge Initial Release
Release v0.1: Antigravity CLI Telegram Bridge Initial Release - 支援 Telegram 到 Antigravity CLI (agy) 的輕量安全橋接 - 單一管理員數字 ID 驗證機制 (ALLOWED_USER_ID) - 支援 Safe 與 Full 雙權限模式及友善權限提示 - 支援自訂 AGY_RULE_PROMPT 注入行為規則 - 內建 /status (系統健康度) 與 /clear (工作階段重置) - 具備逾時控制、輸出大小截斷與敏感憑證自動遮罩 - 提供 systemd 服務一鍵安裝與依賴同步腳本 (install.sh) - 完整單元測試覆蓋 (16/16 測試通過)