abstractassistant 0.3.4__tar.gz → 0.4.0__tar.gz

abstractassistant-0.4.0/ACKNOWLEDGMENTS.md

@@ -0,0 +1,34 @@
+# Acknowledgments
+
+AbstractAssistant is built on top of a number of open-source projects. We’re grateful to all maintainers and contributors.
+
+This list is not exhaustive. The source of truth for install-time dependencies is `pyproject.toml`.
+
+## Core libraries
+
+Agent/runtime foundations:
+- **AbstractAgent** — agent loop + tool calling interface
+- **AbstractRuntime** — durable runs/session storage + tool execution boundary
+- **AbstractCore** — provider-agnostic LLM interface (`create_llm`) and provider/model utilities
+
+UI and desktop integration:
+- **PyQt5** — native UI framework
+- **pystray** — menu bar / system tray integration
+- **Pillow** — tray icon rendering and image utilities
+
+Rendering and UX helpers:
+- **markdown**, **pymdown-extensions** — Markdown rendering
+- **Pygments** — syntax highlighting
+- **pyperclip** — clipboard integration
+- **plyer** — native notifications
+
+Configuration:
+- **tomli** / **tomli-w** — TOML parsing/writing (compatibility across Python versions)
+
+## Optional extras
+
+- **AbstractVoice** — voice/audio capabilities (installed via `abstractassistant[full]` when enabled)
+
+## Development tooling
+
+- **pytest**, **black**, **isort**, **mypy**

{abstractassistant-0.3.4 → abstractassistant-0.4.0}/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to AbstractAssistant will be documented in this file.
 
+## [0.4.0]
+
+### Added
+- **Agent host + durability**: new core modules for agent runs and durable state: `agent_host`, `session_index`, `session_store`, `tool_policy`, `transcript_summary`.
+- **CLI**: `assistant run` for one-turn agentic runs in terminal; `assistant tray` as the explicit tray-mode entry.
+- **Tests**: added basic + integration coverage for the new host/session/tool-policy/summarization components.
+- **Reports**: added research notes under `reports/` (dated 2026-02-04).
+
+### Changed
+- **Docs & README**: rewritten/updated to reflect the agentic host model, tool approval boundary, and install profiles.
+- **Dependencies**: updated `pyproject.toml` (profiles/requirements refined).
+- **Qt bubble UI**: significant updates to `qt_bubble.py` (input/action controls, tool allowlist UI, voice-mode behaviors, theming).
+
+### Fixed
+- **Qt chat bubble input actions**: Fixed first-open layout race that caused the right-side action buttons to overlap. The action column now deterministically sizes to the input row, keeps strict 1:1 square buttons, and preserves 1px vertical spacing.
+- **Tray app shutdown**: Ctrl+C (SIGINT) and SIGTERM now trigger a clean Qt shutdown path (stop timers, hide tray icon, destroy bubble) instead of an abrupt interpreter exit.
+- **Voice toggle icon**: The mic indicator now defaults to a clearly struck "mic off" icon when Full Voice Mode is disabled (non-listening default).
+- **Voice mode UI switch**: Exiting Full Voice Mode now reliably restores the normal interface; while listening, attachment + tools controls remain available and Send is hidden.
+- **Voice mode shutdown**: Stopping Full Voice Mode now force-stops listening/speaking, turns off TTS, restores Ready (green) status, and prevents late STT/TTS callbacks from flipping the UI back to LISTENING.
+
+### Removed
+- `ROADMAP.md` (removed from the repository).
+
+## [0.3.5] - 2026-01-07
+
+### Fixed
+- **Packaging / installability**: narrowed the default `abstractcore[...]` dependency set to avoid GPU-only stacks (notably vLLM) being installed on macOS, which could break `assistant --help` due to transitive `datasets/pyarrow` incompatibilities.
+
 
 ## [0.3.4] - 2025-10-27
 

abstractassistant-0.4.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: abstractassistant
+Version: 0.4.0
+Summary: A sleek (macOS) system tray application providing instant access to LLMs
+Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lpalbou/abstractassistant
+Project-URL: Repository, https://github.com/lpalbou/abstractassistant
+Project-URL: Issues, https://github.com/lpalbou/abstractassistant/issues
+Keywords: ai,llm,macos,system-tray,assistant
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Desktop Environment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: abstractagent>=0.3.0
+Requires-Dist: tomli>=2.0.0; python_version < "3.11"
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: pystray>=0.19.4
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: PyQt5>=5.15.0
+Requires-Dist: markdown>=3.5.0
+Requires-Dist: pygments>=2.16.0
+Requires-Dist: pymdown-extensions>=10.0
+Requires-Dist: pyperclip>=1.8.2
+Requires-Dist: plyer>=2.1.0
+Provides-Extra: lite
+Provides-Extra: full
+Requires-Dist: abstractvoice>=0.6.0; extra == "full"
+Requires-Dist: abstractcore[anthropic,lmstudio,media,ollama,openai,tokens]>=2.11.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Dynamic: license-file
+
+# AbstractAssistant
+
+One-click, tray-accessible agent host for AbstractFramework.
+
+AbstractAssistant runs **agentic** loops (ReAct/CodeAct/MemAct) on top of:
+- **AbstractAgent** (agent patterns)
+- **AbstractRuntime** (durable runs, waits, ledgers)
+- **AbstractCore** (provider/tool normalization)
+- Optional: **AbstractVoice** (STT/TTS)
+
+Docs:
+- `docs/getting-started.md`
+- `docs/architecture.md`
+
+## Install profiles
+
+- `abstractassistant` (default) == `lite`: tray UI + agent backend (no voice)
+- `abstractassistant[full]`: voice (STT/TTS) + broader provider/media extras
+
+```bash
+pip install "abstractassistant"
+# or
+pip install "abstractassistant[full]"
+```
+
+## Quick start
+
+Tray (macOS):
+```bash
+assistant tray
+```
+
+Alias:
+```bash
+abstractassistant tray
+```
+
+Terminal (one turn):
+```bash
+assistant run --prompt "What is in this repo and where do I start?"
+```
+
+Provider/model override:
+```bash
+assistant run --provider ollama --model qwen3:4b-instruct --prompt "Summarize my changes"
+```
+
+## Tool approvals (important)
+
+AbstractAssistant enforces a durable tool boundary:
+- read-only / known-safe tools can auto-run
+- anything else pauses and requires approval (tray dialog or terminal prompt)
+
+This aligns with the framework’s durability + safety model: tools are executed by the host, not persisted as callables inside run state.
+
+## Data & durability
+
+By default, assistant state is stored in `~/.abstractassistant/` (configurable via `--data-dir`):
+- `session.json`: fast UI snapshot (transcript + last run id)
+- `runtime/`: run store + ledger + artifacts (source of truth)
+
+## Development
+
+```bash
+pip install -e ".[dev,lite]"
+python -m pytest -q
+assistant tray --debug
+```
+- **📱 Unobtrusive**: Lives quietly in your menu bar until needed
+- **🔊 Conversational**: Optional voice mode for natural AI interactions
+
+## 📚 Documentation
+
+| Guide | Description |
+|-------|------------|
+| [📖 Installation Guide](docs/installation.md) | Complete setup instructions, prerequisites, and troubleshooting |
+| [🎯 Getting Started Guide](docs/getting-started.md) | Step-by-step usage guide with all features explained |
+| [🏗️ Architecture Guide](docs/architecture.md) | Technical documentation and development information |
+
+## 📋 Requirements
+
+- **macOS**: 10.14+ (Mojave or later)
+- **Python**: 3.9+
+- **Qt Framework**: PyQt5, PySide2, or PyQt6 (automatically detected)
+- **Dependencies**: [AbstractCore](https://github.com/lpalbou/abstractcore) and [AbstractVoice](https://github.com/lpalbou/abstractvoice) (automatically installed)
+
+## 🤝 Contributing
+
+Contributions welcome! Please read the architecture documentation and follow the established patterns:
+
+- **Clean Code**: Follow PEP 8 and use type hints
+- **Modular Design**: Keep components focused and reusable
+- **Modern UI/UX**: Maintain the sleek, native feel
+- **Error Handling**: Always include graceful fallbacks
+- **Documentation**: Update docs for any new features
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+## 🙏 Acknowledgments
+
+AbstractAssistant is built on excellent open-source projects:
+
+### Core Dependencies
+- **[AbstractCore](https://github.com/lpalbou/abstractcore)**: Universal LLM interface - enables seamless multi-provider support
+- **[AbstractVoice](https://github.com/lpalbou/abstractvoice)**: High-quality text-to-speech engine with natural voice synthesis
+
+### Framework & UI
+- **[PyQt5/PySide2/PyQt6](https://www.qt.io/)**: Cross-platform GUI framework for the modern interface
+- **[pystray](https://github.com/moses-palmer/pystray)**: Cross-platform system tray integration
+- **[Pillow](https://python-pillow.org/)**: Image processing for dynamic icon generation
+
+### Part of the AbstractX Ecosystem
+AbstractAssistant integrates seamlessly with other AbstractX projects:
+- 🧠 **[AbstractCore](https://github.com/lpalbou/abstractcore)**: Universal LLM provider interface
+- 🗣️ **[AbstractVoice](https://github.com/lpalbou/abstractvoice)**: Advanced text-to-speech capabilities
+
+See [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md) for complete attribution.
+
+---
+
+**Built with ❤️ for macOS users who want AI at their fingertips**

abstractassistant-0.4.0/README.md

@@ -0,0 +1,123 @@
+# AbstractAssistant
+
+One-click, tray-accessible agent host for AbstractFramework.
+
+AbstractAssistant runs **agentic** loops (ReAct/CodeAct/MemAct) on top of:
+- **AbstractAgent** (agent patterns)
+- **AbstractRuntime** (durable runs, waits, ledgers)
+- **AbstractCore** (provider/tool normalization)
+- Optional: **AbstractVoice** (STT/TTS)
+
+Docs:
+- `docs/getting-started.md`
+- `docs/architecture.md`
+
+## Install profiles
+
+- `abstractassistant` (default) == `lite`: tray UI + agent backend (no voice)
+- `abstractassistant[full]`: voice (STT/TTS) + broader provider/media extras
+
+```bash
+pip install "abstractassistant"
+# or
+pip install "abstractassistant[full]"
+```
+
+## Quick start
+
+Tray (macOS):
+```bash
+assistant tray
+```
+
+Alias:
+```bash
+abstractassistant tray
+```
+
+Terminal (one turn):
+```bash
+assistant run --prompt "What is in this repo and where do I start?"
+```
+
+Provider/model override:
+```bash
+assistant run --provider ollama --model qwen3:4b-instruct --prompt "Summarize my changes"
+```
+
+## Tool approvals (important)
+
+AbstractAssistant enforces a durable tool boundary:
+- read-only / known-safe tools can auto-run
+- anything else pauses and requires approval (tray dialog or terminal prompt)
+
+This aligns with the framework’s durability + safety model: tools are executed by the host, not persisted as callables inside run state.
+
+## Data & durability
+
+By default, assistant state is stored in `~/.abstractassistant/` (configurable via `--data-dir`):
+- `session.json`: fast UI snapshot (transcript + last run id)
+- `runtime/`: run store + ledger + artifacts (source of truth)
+
+## Development
+
+```bash
+pip install -e ".[dev,lite]"
+python -m pytest -q
+assistant tray --debug
+```
+- **📱 Unobtrusive**: Lives quietly in your menu bar until needed
+- **🔊 Conversational**: Optional voice mode for natural AI interactions
+
+## 📚 Documentation
+
+| Guide | Description |
+|-------|------------|
+| [📖 Installation Guide](docs/installation.md) | Complete setup instructions, prerequisites, and troubleshooting |
+| [🎯 Getting Started Guide](docs/getting-started.md) | Step-by-step usage guide with all features explained |
+| [🏗️ Architecture Guide](docs/architecture.md) | Technical documentation and development information |
+
+## 📋 Requirements
+
+- **macOS**: 10.14+ (Mojave or later)
+- **Python**: 3.9+
+- **Qt Framework**: PyQt5, PySide2, or PyQt6 (automatically detected)
+- **Dependencies**: [AbstractCore](https://github.com/lpalbou/abstractcore) and [AbstractVoice](https://github.com/lpalbou/abstractvoice) (automatically installed)
+
+## 🤝 Contributing
+
+Contributions welcome! Please read the architecture documentation and follow the established patterns:
+
+- **Clean Code**: Follow PEP 8 and use type hints
+- **Modular Design**: Keep components focused and reusable
+- **Modern UI/UX**: Maintain the sleek, native feel
+- **Error Handling**: Always include graceful fallbacks
+- **Documentation**: Update docs for any new features
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+## 🙏 Acknowledgments
+
+AbstractAssistant is built on excellent open-source projects:
+
+### Core Dependencies
+- **[AbstractCore](https://github.com/lpalbou/abstractcore)**: Universal LLM interface - enables seamless multi-provider support
+- **[AbstractVoice](https://github.com/lpalbou/abstractvoice)**: High-quality text-to-speech engine with natural voice synthesis
+
+### Framework & UI
+- **[PyQt5/PySide2/PyQt6](https://www.qt.io/)**: Cross-platform GUI framework for the modern interface
+- **[pystray](https://github.com/moses-palmer/pystray)**: Cross-platform system tray integration
+- **[Pillow](https://python-pillow.org/)**: Image processing for dynamic icon generation
+
+### Part of the AbstractX Ecosystem
+AbstractAssistant integrates seamlessly with other AbstractX projects:
+- 🧠 **[AbstractCore](https://github.com/lpalbou/abstractcore)**: Universal LLM provider interface
+- 🗣️ **[AbstractVoice](https://github.com/lpalbou/abstractvoice)**: Advanced text-to-speech capabilities
+
+See [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md) for complete attribution.
+
+---
+
+**Built with ❤️ for macOS users who want AI at their fingertips**

{abstractassistant-0.3.4 → abstractassistant-0.4.0}/abstractassistant/app.py

@@ -6,6 +6,8 @@ Handles system tray integration, UI coordination, and application lifecycle.
 
 import threading
 import time
+import signal
+from pathlib import Path
 from typing import Optional
 
 import pystray
@@ -131,17 +133,26 @@ class EnhancedClickableIcon(pystray.Icon):
 class AbstractAssistantApp:
     """Main application class coordinating all components."""
     
-    def __init__(self, config: Optional[Config] = None, debug: bool = False, listening_mode: str = "wait"):
+    def __init__(
+        self,
+        config: Optional[Config] = None,
+        debug: bool = False,
+        listening_mode: str = "wait",
+        *,
+        data_dir: Optional[Path] = None,
+    ):
         """Initialize the AbstractAssistant application.
 
         Args:
             config: Configuration object (uses default if None)
             debug: Enable debug mode
             listening_mode: Voice listening mode (none, stop, wait, full)
+            data_dir: Assistant base data dir (sessions + runtime stores)
         """
         self.config = config or Config.default()
         self.debug = debug
         self.listening_mode = listening_mode
+        self.data_dir = Path(data_dir).expanduser() if data_dir is not None else None
         
         # Validate configuration
         if not self.config.validate():
@@ -152,7 +163,7 @@ class AbstractAssistantApp:
         # Initialize components
         self.icon: Optional[pystray.Icon] = None
         self.bubble_manager: Optional[QtBubbleManager] = None
-        self.llm_manager: LLMManager = LLMManager(config=self.config, debug=self.debug)
+        self.llm_manager: LLMManager = LLMManager(config=self.config, debug=self.debug, data_dir=self.data_dir)
         self.icon_generator: IconGenerator = IconGenerator(size=self.config.system_tray.icon_size)
         
         # Application state
@@ -786,6 +797,20 @@ class AbstractAssistantApp:
         
         if self.icon:
             self.icon.stop()
+
+        # Stop/hide Qt tray icon if we are running in Qt mode.
+        try:
+            if hasattr(self, "qt_tray_icon") and self.qt_tray_icon is not None:
+                self.qt_tray_icon.hide()
+        except Exception:
+            pass
+
+        # Stop click timer used for single/double click detection (Qt mode).
+        try:
+            if hasattr(self, "click_timer") and self.click_timer is not None:
+                self.click_timer.stop()
+        except Exception:
+            pass
         
         # Clean up bubble manager
         if self.bubble_manager:
@@ -797,6 +822,20 @@ class AbstractAssistantApp:
         
         if self.debug:
             print("✅ AbstractAssistant quit successfully")
+
+    def _request_qt_quit(self) -> None:
+        """Request a graceful quit on the Qt event loop (safe to call from SIGINT handler)."""
+        # Always run cleanup first; then quit the Qt event loop.
+        try:
+            self.quit_application()
+        except Exception:
+            pass
+
+        try:
+            if hasattr(self, "qt_app") and self.qt_app:
+                self.qt_app.quit()
+        except Exception:
+            pass
     
     def run(self):
         """Start the application using Qt event loop for proper threading."""
@@ -833,15 +872,39 @@ class AbstractAssistantApp:
                 print("AbstractAssistant started. Check your menu bar!")
                 print("Click the icon to open the chat interface.")
 
+            # Ctrl+C / SIGTERM should shut down cleanly (avoid macOS "python quit unexpectedly").
+            # We schedule the quit on the Qt loop to keep teardown ordered.
+            def _handle_sigint(_signum, _frame):
+                try:
+                    QTimer.singleShot(0, self._request_qt_quit)
+                except Exception:
+                    self._request_qt_quit()
+
+            try:
+                signal.signal(signal.SIGINT, _handle_sigint)
+                signal.signal(signal.SIGTERM, _handle_sigint)
+            except Exception:
+                # If signals are not available/allowed in this context, we still handle KeyboardInterrupt below.
+                pass
+
             # Run Qt event loop (this blocks until quit)
-            self.qt_app.exec_()
+            try:
+                self.qt_app.exec_()
+            except KeyboardInterrupt:
+                # Ensure a graceful shutdown when Ctrl+C interrupts the event loop.
+                self._request_qt_quit()
+                return
 
         except ImportError:
             if self.debug:
                 print("❌ PyQt5 not available. Falling back to pystray...")
             # Fallback to original pystray implementation
             self.icon = self.create_system_tray_icon()
-            self.icon.run()
+            try:
+                self.icon.run()
+            except KeyboardInterrupt:
+                self.quit_application()
+                return
 
     def _create_qt_system_tray_icon(self):
         """Create Qt-based system tray icon with smooth animations."""
@@ -996,5 +1059,5 @@ class AbstractAssistantApp:
         if self.debug:
             print("🔄 Qt: Quit requested")
 
-        if hasattr(self, 'qt_app') and self.qt_app:
-            self.qt_app.quit()
+        # Route through the same cleanup path (menu Quit should behave like Ctrl+C).
+        self._request_qt_quit()

abstractassistant-0.4.0/abstractassistant/cli.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""CLI entry point for AbstractAssistant.
+
+Packaging invariant:
+- `assistant --help` must not import GUI/voice stacks (optional dependencies).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create the command-line argument parser."""
+    prog = Path(sys.argv[0]).name if sys.argv and sys.argv[0] else "abstractassistant"
+    parser = argparse.ArgumentParser(prog=prog, description="AbstractAssistant (agentic tray + CLI)")
+    
+    parser.add_argument("--version", action="version", version="abstractassistant (agentic) v1")
+    
+    parser.add_argument("--config", type=str, default=None, help="Path to config.toml (optional)")
+    parser.add_argument("--provider", type=str, default=None, help="LLM provider id (e.g. ollama, lmstudio, openai)")
+    parser.add_argument("--model", type=str, default=None, help="Model name/id for the provider")
+    parser.add_argument("--agent", type=str, default=None, choices=["react", "codeact", "memact"], help="Agent kind")
+    parser.add_argument("--data-dir", type=str, default=None, help="Assistant data dir (runtime stores + session)")
+    parser.add_argument("--workspace-root", type=str, default=None, help="Workspace root for filesystem-ish tools")
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging")
+    
+    sub = parser.add_subparsers(dest="command")
+    
+    tray = sub.add_parser("tray", help="Run the macOS tray app")
+    tray.add_argument(
+        "--listening-mode",
+        type=str,
+        choices=["none", "stop", "wait", "full", "ptt"],
+        default="wait",
+        help="Voice listening mode (requires [full] extra for STT/TTS)",
+    )
+
+    run = sub.add_parser("run", help="Run one agentic turn in the terminal")
+    run.add_argument("--prompt", type=str, required=True, help="User prompt text")
+    run.add_argument("--approve-all-tools", action="store_true", help="Auto-approve all tool calls (dangerous)")
+    
+    return parser
+
+
+def find_config_file(config_path: Optional[str] = None) -> Optional[Path]:
+    """Find the configuration file."""
+    if config_path:
+        config_file = Path(config_path)
+        if config_file.exists():
+            return config_file
+        else:
+            print(f"Warning: Config file '{config_path}' not found.")
+            return None
+    
+    # Look for config.toml in current directory, then package directory
+    current_dir = Path.cwd()
+    package_dir = Path(__file__).parent.parent
+    
+    for directory in [current_dir, package_dir]:
+        config_file = directory / "config.toml"
+        if config_file.exists():
+            return config_file
+    
+    return None
+
+
+def main() -> int:
+    """Main entry point for the CLI."""
+    parser = create_parser()
+    args = parser.parse_args()
+    
+    try:
+        command = args.command or "tray"
+
+        if command == "run":
+            from .core.agent_host import AgentHost, AgentHostConfig
+
+            provider = str(args.provider or "ollama")
+            model = str(args.model or "qwen3:4b-instruct")
+            agent_kind = str(args.agent or "react")
+            data_dir = Path(args.data_dir).expanduser() if args.data_dir else (Path.home() / ".abstractassistant")
+
+            host = AgentHost(
+                AgentHostConfig(
+                    provider=provider,
+                    model=model,
+                    agent_kind=agent_kind,
+                    data_dir=data_dir,
+                    workspace_root=args.workspace_root,
+                )
+            )
+
+            def _approve(tool_calls):
+                if args.approve_all_tools:
+                    return True
+                # Prompt for dangerous/unknown batches; safe-only batches auto-approve.
+                if not host.tool_policy.requires_approval(tool_calls):
+                    return True
+                print("\nTool approval required:")
+                for tc in tool_calls:
+                    name = tc.get("name")
+                    arguments = tc.get("arguments")
+                    print(f"- {name}({arguments})")
+                ans = input("Approve this batch? [y/N] ").strip().lower()
+                return ans in {"y", "yes"}
+
+            def _ask_user(wait):
+                prompt = str(getattr(wait, "prompt", "") or "Input required:")
+                return input(f"\n{prompt}\n> ").strip()
+
+            final = ""
+            for ev in host.run_turn(user_text=args.prompt, approve_tools=_approve, ask_user=_ask_user):
+                typ = ev.get("type")
+                if typ == "assistant":
+                    final = str(ev.get("content") or "")
+                if typ == "error":
+                    raise RuntimeError(str(ev.get("error") or "error"))
+            print(final)
+            return 0
+
+        # tray (default)
+        try:
+            from .config import Config  # lightweight
+
+            config_file = find_config_file(args.config)
+            config = Config.from_file(config_file) if config_file else Config.default()
+            if args.provider:
+                config.llm.default_provider = str(args.provider)
+            if args.model:
+                config.llm.default_model = str(args.model)
+        except Exception:
+            config = None
+
+        try:
+            from .app import AbstractAssistantApp
+        except Exception as e:
+            print("AbstractAssistant tray mode requires GUI dependencies.")
+            print('Install (tray): pip install -U "abstractassistant"')
+            print('Install (tray + voice): pip install -U "abstractassistant[full]"')
+            print('From source (editable): pip install -e ".[lite]"')
+            print(f"Import error: {e}")
+            return 2
+
+        app = AbstractAssistantApp(
+            config=config,
+            debug=bool(args.debug),
+            listening_mode=str(getattr(args, "listening_mode", "wait")),
+            data_dir=Path(args.data_dir).expanduser() if getattr(args, "data_dir", None) else None,
+        )
+        app.run()
+        return 0
+        
+    except KeyboardInterrupt:
+        print("\n👋 AbstractAssistant stopped by user")
+        return 0
+    except Exception as e:
+        print(f"❌ Error starting AbstractAssistant: {e}")
+        if getattr(args, "debug", False):
+            import traceback
+
+            traceback.print_exc()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())