8000 Releases · gemini960114/HostSpark · GitHub
[go: up one dir, main page]

Skip to content

Releases

v0.4.5 - Decoupled Constants & Prompts, Multimodal Attachments, and Unified SSOT

Choose a tag to compare

@gemini960114 gemini960114 released this 04 Sep 05:21

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(), and build_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-chat uploads/ 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.
  • Video & Document Ingestion:
    • Direct upload support for vid 8000 eos (.mp4, .mov, .mkv) and documents (.pdf, .txt, .py, .json, .csv, .md, etc.).
  • Strict Safe Whitelisting:
    • Any uploaded file whose extension is not in SAFE_EXTENSIONS is safely rejected with an informative list of supported formats, preventing arbitrary or hazardous file staging.
  • 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, and hostspark.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.py with DEFAULT_CIRCUIT_BREAKER_MAX_FAILURES.
  • /schedule_list and /schedule_show now 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-level edge-tts and pillow installations.
    • Added documentation explaining why system Python is targeted for AGY standalone binary execution.

📖 Documentation Updates

  • Updated README.md and README.zh-TW.md:
    • Added architectural decoupling and unified constants in Key Features.
    • Added /tokens, /compact, and /learn commands 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.service

HostSpark v0.4.4

Choose a tag to compare

@gemini960114 gemini960114 released this 04 Sep 02:28

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: Added nonlocal last_edit_time to the nested keep_typing() coroutine inside src/hostspark/telegram/dispatcher.py.
  • Previously, assigning to last_edit_time within the inner coroutine without nonlocal caused 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_SECONDS from 600s (10 minutes) to 180s (3 minutes) in .env.example and documentation, preventing excessive waiting periods if a task stalls.
  • Anti-Blocking Rule Prompt: Updated prompt recommendations in .env.example advising the assistant to:
    1. Never read continuous stdout streams without finite limits (e.g. head /var/log/apache2/access.log in Docker containers whose stdout pipes never reach EOF). Always use docker logs --tail N or strict timeouts (timeout 5s ...).
    2. Background daemon processes immediately.

📖 Documentation Updates

  • Updated README.md and README.zh-TW.md to detail:
    • Active heartbeat timer and stall warnings in feature highlights.
    • /cancel progress 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.service

HostSpark v0.4.3

Choose a tag to compare

@gemini960114 gemini960114 released this 04 Sep 02:00

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.md directly 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 nohup tunnels are terminated by the agent environment's process reaper when awaiting user input or on context reset. Promoted Docker containerization (cloudflare/cloudflared:latest with --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.com tunnels 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.sh to 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 urlparse to prevent handler crashes on complex markdown links with query parameters or relative paths (2167a68).

⚙️ Configuration & Documentation

  • Streaming Verbosity (AGY_VERBOSE): Documented AGY_VERBOSE in .env.example and README.md (detailed for full thinking traces, compact for single-line summaries, silent to 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.sh

The install script will automatically sync the bundled skills to your global AGY configuration and restart the service.

HostSpark v0.4.2

Choose a tag to compare

@gemini960114 gemini960114 released this 03 Sep 15:15

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 new validate_project_dir_name()
    allowlist plus the existing safe_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.
  • /new with no argument lists existing project directories as buttons
    (current one checkmarked), mirroring the /model picker. The button
    callback validates the name too, not just the typed-argument path.
  • /clear is decoupled from /new and keeps the old "just reset the
    conversation, keep the working directory" behavior.
  • Switching to a genuinely different project directory also clears any
    /add_dir entries 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 /new are completely unaffected.
  • New .env vars: 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 /new is 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 subprocess cwd points at it
    -- without --add-dir <dir> it silently
    falls back to its own internal scratch location
    (~/.gemini/antigravity-cli/scratch) regardless of cwd. run_agy() now
    always passes --add-dir for whatever directory it resolves.
  • /new and /clear weren't actually starting a fresh agy session.
    HostSpark never persisted a conversation_id back from agy's replies, so it
    was already None on every ordinary turn -- meaning every message fell
    through to the --continue branch regardless of what /new//clear had
    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/--conversation for exactly the next turn after a switch or
    /clear, kept deliberately separate from the pre-existing, sticky
    /new_project on|off toggle so that manual setting can't be broken by it
    (caught by a dedicated regression test before shipping).

New: simplified model + effort selection

  • /model used 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
    new resolve_model_and_effort_args() recombines them into the real
    --model value 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.db gains a workspace_dir column via an idempotent migration
    that runs automatically on startup (guarded by a PRAGMA table_info
    check, so it's safe to restart repeatedly). Verified against a snapshot of
    a live database before release; back up chat_state.db before upgrading
    as a precaution regardless.
  • Re-run ./install.sh to pick up the new package version and restart the
    service.
  • If AGY_WORKSPACE_ROOT/AGY_WORKDIR are 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 /new themselves; nothing is migrated automatically.

HostSpark v0.4.1

Choose a tag to compare

@gemini960114 gemini960114 released this 03 Sep 08:55

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.sh to 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

Choose a tag to compare

@gemini960114 gemini960114 released this 03 Sep 08:44

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
    hostspark console script and python -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.sh to 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

Choose a tag to compare

@gemini960114 gemini960114 released this 01 Sep 17:50

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 --continue could silently resume a different chat's conversation.
  • Live streaming & CLI passthrough: streamed AGY progress, PTY-fallback quota/context queries (/usage, /quota, /context), and /agy CLI passthrough with two-phase confirmation for dangerous commands.
  • Scheduling & job queue: deterministic natural-language schedule-intent detection (routes straight into /schedule_add instead 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/--effort conflicts, a /status HTML-escaping bug, /restart//update now correctly triggers systemd's Restart=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 /usage or /context query.
  • Removed /resume, /sessions, and the /continue browsing 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 into SECURITY.md); install.sh translated to English; README.md/INSTALL_BY_AI.md are now English by default with linked README.zh-TW.md / INSTALL_BY_AI.zh-TW.md Traditional Chinese counterparts.

v0.2: Host-level Persistent Scheduling, Workspace Isolation & Customizable Waiting Messages

Choose a tag to compare

@gemini960114 gemini960114 released this 30 Aug 09:57

🚀 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

Choose a tag to compare

@gemini960114 gemini960114 released this 30 Aug 09:02
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 測試通過)
0