flowjet 2.0.3__tar.gz → 2.0.4__tar.gz

{flowjet-2.0.3 → flowjet-2.0.4}/CHANGELOG.md

@@ -10,6 +10,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.4] — 2026-09-19
+
+### Changed
+
+- Bumped `soothe` lower bound to `1.0.13` (was `1.0.12`). soothe-nano stays
+  pinned at `>=1.2.28,<1.3.0`.
+
 ## [2.0.3] — 2026-09-18
 
 ### Added

{flowjet-2.0.3 → flowjet-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowjet
-Version: 2.0.3
+Version: 2.0.4
 Summary: FlowJet — agent CLI (fj) and server (ACP + OpenAI-compatible HTTP) powered by soothe-nano
 Project-URL: Homepage, https://github.com/caesar0301/flowjet
 Project-URL: Repository, https://github.com/caesar0301/flowjet
@@ -23,7 +23,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.11
 Requires-Dist: soothe-nano<1.3.0,>=1.2.28
-Requires-Dist: soothe<2.0.0,>=1.0.12
+Requires-Dist: soothe<2.0.0,>=1.0.13
 Provides-Extra: dev
 Requires-Dist: httpx>=0.27.0; extra == 'dev'
 Requires-Dist: mypy>=1.0.0; extra == 'dev'

{flowjet-2.0.3 → flowjet-2.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flowjet"
-version = "2.0.3"
+version = "2.0.4"
 description = "FlowJet — agent CLI (fj) and server (ACP + OpenAI-compatible HTTP) powered by soothe-nano"
 readme = "README.md"
 license = { text = "MIT" }
@@ -31,7 +31,7 @@ classifiers = [
 dependencies = [
     # Default CLI runtime (FLOWJET_BACKEND=soothe). soothe is a host layer over
     # soothe-nano, so nano stays pinned explicitly: soothe only caps it at <2.
-    "soothe>=1.0.12,<2.0.0",
+    "soothe>=1.0.13,<2.0.0",
     "soothe-nano>=1.2.28,<1.3.0",
 ]
 

{flowjet-2.0.3 → flowjet-2.0.4}/src/flowjet/cli/agent.py

@@ -8,14 +8,12 @@ Nano bootstrap, config loading and the builtin-skill root now live in
 from __future__ import annotations
 
 import logging
-import os
-import sys
-from logging.handlers import RotatingFileHandler
 from pathlib import Path
 from typing import Any
 
 from soothe_nano.config import SootheConfig
 
+from flowjet.cli.cli import _CompactConsoleFormatter
 from flowjet.core.bootstrap import (
     BUILTIN_SKILLS_DIR,
     FJ_CORE_SKILL_NAMES,
@@ -31,6 +29,27 @@ from flowjet.core.modes import CLI_PROFILE, apply_profile
 
 logger = logging.getLogger(__name__)
 
+# ---------------------------------------------------------------------------
+# CLI logging (delegated to ``flowjet.cli.cli`` at call time)
+# ---------------------------------------------------------------------------
+
+
+def configure_cli_logging(*, verbose: bool = False) -> None:
+    """Quiet the console for one-shot CLI use (see ``flowjet.cli.cli``).
+
+    Delegated dynamically so monkeypatching ``flowjet.cli.cli.configure_cli_logging``
+    (as tests do via ``monkeypatch.setattr(cli, ...)``) is honored here too.
+    """
+    from flowjet.cli import cli as _cli
+
+    _cli.configure_cli_logging(verbose=verbose)
+
+
+def silence_after_plugins(*, verbose: bool = False) -> None:
+    """Re-apply quieting after plugin imports (belt-and-suspenders)."""
+    configure_cli_logging(verbose=verbose)
+
+
 # ---------------------------------------------------------------------------
 # Builtin skills (re-exported; owned by flowjet.core.bootstrap)
 # ---------------------------------------------------------------------------
@@ -57,73 +76,6 @@ def apply_fj_defaults(config: SootheConfig) -> SootheConfig:
     return apply_profile(config, CLI_PROFILE)
 
 
-# ---------------------------------------------------------------------------
-# CLI logging
-# ---------------------------------------------------------------------------
-
-_BROWSER_USE_SETUP_LOGGING = "BROWSER_USE_SETUP_LOGGING"
-_FJ_CONSOLE_HANDLER = "fj-console"
-
-
-class _CompactConsoleFormatter(logging.Formatter):
-    """One-line console records without exception tracebacks."""
-
-    def formatException(self, ei: object) -> str:  # noqa: N802 - logging API
-        return ""
-
-    def format(self, record: logging.LogRecord) -> str:
-        # logger.exception sets exc_info; drop it so format() stays one line.
-        record.exc_info = None
-        record.exc_text = None
-        return super().format(record)
-
-
-def configure_cli_logging(*, verbose: bool = False) -> None:
-    """Quiet the console for one-shot CLI use.
-
-    - Opt out of ``browser_use`` import-time root logger setup when unset.
-    - Remove existing root stream handlers (stderr/stdout) so init INFO
-      lines do not interleave with the agent answer.
-    - Prevent ``lastResort`` traceback dumps from soothe tool failures.
-    - When ``verbose``, show WARNING+ as single-line messages on stderr.
-    """
-    os.environ.setdefault(_BROWSER_USE_SETUP_LOGGING, "false")
-    _remove_root_console_handlers()
-    root = logging.getLogger()
-    if verbose:
-        handler = logging.StreamHandler(sys.stderr)
-        handler.set_name(_FJ_CONSOLE_HANDLER)
-        handler.setLevel(logging.WARNING)
-        handler.setFormatter(_CompactConsoleFormatter("%(message)s"))
-        root.addHandler(handler)
-    elif not root.handlers:
-        null = logging.NullHandler()
-        null.set_name(_FJ_CONSOLE_HANDLER)
-        root.addHandler(null)
-    if root.level < logging.WARNING:
-        root.setLevel(logging.WARNING)
-
-
-def silence_after_plugins(*, verbose: bool = False) -> None:
-    """Re-apply quieting after plugin imports (belt-and-suspenders)."""
-    configure_cli_logging(verbose=verbose)
-
-
-def _remove_root_console_handlers() -> None:
-    root = logging.getLogger()
-    for handler in list(root.handlers):
-        if isinstance(handler, RotatingFileHandler):
-            continue
-        if isinstance(handler, logging.FileHandler):
-            continue
-        if isinstance(handler, logging.StreamHandler) or isinstance(handler, logging.NullHandler):
-            root.removeHandler(handler)
-            try:
-                handler.close()
-            except Exception:  # pragma: no cover - defensive
-                pass
-
-
 # ---------------------------------------------------------------------------
 # Agent build
 # ---------------------------------------------------------------------------
@@ -165,6 +117,7 @@ async def build_agent(
 __all__ = [
     "BUILTIN_SKILLS_DIR",
     "FJ_CORE_SKILL_NAMES",
+    "_CompactConsoleFormatter",
     "apply_fj_defaults",
     "build_agent",
     "configure_cli_logging",

{flowjet-2.0.3 → flowjet-2.0.4}/src/flowjet/cli/cli.py

@@ -8,18 +8,113 @@ from __future__ import annotations
 import argparse
 import asyncio
 import contextlib
+import logging
+import os
 import sys
 from collections.abc import Coroutine
+from logging.handlers import RotatingFileHandler
 from pathlib import Path
 from typing import Any
 
 from flowjet.cli import __version__
-from flowjet.cli.agent import configure_cli_logging
 
 FORMAL_CLI = "flowjet"
 CLI_ALIASES = frozenset({"fj", "fjf", FORMAL_CLI})
 
 
+# ---------------------------------------------------------------------------
+# CLI logging — stdlib only, kept here so ``fj -V`` / ``fj -h`` never pay the
+# heavy ``soothe_nano`` / ``flowjet.core.bootstrap`` import cost.
+# ---------------------------------------------------------------------------
+
+_BROWSER_USE_SETUP_LOGGING = "BROWSER_USE_SETUP_LOGGING"
+_FJ_CONSOLE_HANDLER = "fj-console"
+
+
+class _CompactConsoleFormatter(logging.Formatter):
+    """One-line console records without exception tracebacks."""
+
+    def formatException(self, ei: object) -> str:  # noqa: N802 - logging API
+        return ""
+
+    def format(self, record: logging.LogRecord) -> str:
+        # logger.exception sets exc_info; drop it so format() stays one line.
+        record.exc_info = None
+        record.exc_text = None
+        return super().format(record)
+
+
+_FILE_LOGGING_INSTALLED = False
+
+
+def configure_cli_logging(*, verbose: bool = False) -> None:
+    """Quiet the console for one-shot CLI use and enable file logging by default.
+
+    - Opt out of ``browser_use`` import-time root logger setup when unset.
+    - Remove existing root stream handlers (stderr/stdout) so init INFO
+      lines do not interleave with the agent answer.
+    - Prevent ``lastResort`` traceback dumps from soothe tool failures.
+    - When ``verbose``, show WARNING+ as single-line messages on stderr.
+    - Attach a rotating file handler at ``<FLOWJET_HOME>/logs/cli.log`` so
+      every CLI run is recorded by default (idempotent across re-invocations
+      within the same process, e.g. tests).
+    """
+    os.environ.setdefault(_BROWSER_USE_SETUP_LOGGING, "false")
+    _remove_root_console_handlers()
+    root = logging.getLogger()
+    if verbose:
+        handler = logging.StreamHandler(sys.stderr)
+        handler.set_name(_FJ_CONSOLE_HANDLER)
+        handler.setLevel(logging.WARNING)
+        handler.setFormatter(_CompactConsoleFormatter("%(message)s"))
+        root.addHandler(handler)
+    elif not root.handlers:
+        null = logging.NullHandler()
+        null.set_name(_FJ_CONSOLE_HANDLER)
+        root.addHandler(null)
+    if root.level < logging.WARNING:
+        root.setLevel(logging.WARNING)
+
+    _ensure_cli_file_logging()
+
+
+def _ensure_cli_file_logging() -> None:
+    """Attach the rotating file handler for CLI runs (idempotent)."""
+    global _FILE_LOGGING_INSTALLED
+    if _FILE_LOGGING_INSTALLED:
+        return
+    try:
+        from flowjet.core.home import cli_log_path, ensure_flowjet_home
+
+        ensure_flowjet_home()
+        from soothe_nano.logging.setup import setup_logging
+
+        setup_logging(log_file=str(cli_log_path()), extra_logger_names=("flowjet",))
+        _FILE_LOGGING_INSTALLED = True
+    except Exception:  # pragma: no cover - logging must never break the CLI
+        pass
+
+
+def silence_after_plugins(*, verbose: bool = False) -> None:
+    """Re-apply quieting after plugin imports (belt-and-suspenders)."""
+    configure_cli_logging(verbose=verbose)
+
+
+def _remove_root_console_handlers() -> None:
+    root = logging.getLogger()
+    for handler in list(root.handlers):
+        if isinstance(handler, RotatingFileHandler):
+            continue
+        if isinstance(handler, logging.FileHandler):
+            continue
+        if isinstance(handler, logging.StreamHandler) or isinstance(handler, logging.NullHandler):
+            root.removeHandler(handler)
+            try:
+                handler.close()
+            except Exception:  # pragma: no cover - defensive
+                pass
+
+
 def resolve_cli_prog(argv0: str | None = None) -> str:
     """Return the invoked command name for help / version strings.
 
@@ -217,6 +312,13 @@ class _HelpFormatter(argparse.RawDescriptionHelpFormatter):
     def __init__(self, prog: str) -> None:
         super().__init__(prog, max_help_position=26, width=92)
 
+    def _format_action(self, action: argparse.Action) -> str:  # type: ignore[override]
+        # Resolve lazy help strings only when help is actually rendered, so
+        # ``-V`` never pays for the import behind ``_default_config_help``.
+        if isinstance(action.help, _LazyHelp):
+            action.help = str(action.help)
+        return super()._format_action(action)
+
 
 def _default_config_help() -> str:
     from flowjet.cli.agent import default_config_path
@@ -224,6 +326,26 @@ def _default_config_help() -> str:
     return f"Alternate nano.yml (default: {default_config_path()})"
 
 
+class _LazyHelp:
+    """Resolve a help-string callable only when argparse reads it.
+
+    ``-V`` / ``-h``-without-our-flag paths never touch the help text, so the
+    heavy import behind ``_default_config_help`` stays deferred until a flag
+    that actually shows help (``-h``) or errors is invoked.
+    """
+
+    __slots__ = ("_factory", "_cached")
+
+    def __init__(self, factory: Any) -> None:
+        self._factory = factory
+        self._cached: str | None = None
+
+    def __str__(self) -> str:
+        if self._cached is None:
+            self._cached = self._factory()
+        return self._cached
+
+
 def _build_parser(prog: str | None = None) -> argparse.ArgumentParser:
     cli_prog = prog or resolve_cli_prog()
     parser = argparse.ArgumentParser(
@@ -297,7 +419,7 @@ def _build_parser(prog: str | None = None) -> argparse.ArgumentParser:
         "-c",
         "--config",
         metavar="PATH",
-        help=_default_config_help(),
+        help=_LazyHelp(_default_config_help),
     )
     paths.add_argument(
         "-w",
@@ -324,7 +446,7 @@ def _build_setup_parser(prog: str | None = None) -> argparse.ArgumentParser:
         "-c",
         "--config",
         metavar="PATH",
-        help=_default_config_help(),
+        help=_LazyHelp(_default_config_help),
     )
     return parser
 
@@ -565,8 +687,17 @@ def main_follow(argv: list[str] | None = None) -> int:
 
 def main(argv: list[str] | None = None) -> int:
     try:
-        configure_cli_logging()
+        # Align SOOTHE_HOME with FLOWJET_HOME before any soothe import so
+        # config, data, and logs all land under ~/.flowjet. Must run first:
+        # soothe_sdk.paths binds SOOTHE_HOME at import time.
+        from flowjet.core.home import ensure_flowjet_home
+
+        ensure_flowjet_home()
+        # Parse first so ``-V`` / ``-h`` / ``--help`` exit before we touch the
+        # logging stack (and the heavy ``flowjet.cli.agent`` import it used to
+        # drag in). Version/help must stay instant.
         args = parse_args(argv)
+        configure_cli_logging()
         # Re-apply after parse so ``-v`` can enable compact console warnings.
         if getattr(args, "verbose", False):
             configure_cli_logging(verbose=True)

flowjet-2.0.4/src/flowjet/core/home.py

@@ -0,0 +1,127 @@
+"""Align ``SOOTHE_HOME`` with ``FLOWJET_HOME`` and enable file logging by default.
+
+FlowJet ships its own home directory (``~/.flowjet``) distinct from Soothe's
+default (``~/.soothe``). Soothe-nano reads ``SOOTHE_HOME`` once at import time
+(``soothe_sdk.paths``), so this module must run *before* any soothe import.
+
+Call :func:`ensure_flowjet_home` at the top of every entry point
+(``flowjet.cli.cli.main``, ``flowjet.server.__main__.main``). It is idempotent
+and safe to call from tests.
+
+Resolution order for the shared home:
+1. ``FLOWJET_HOME`` env var (if set)
+2. ``SOOTHE_HOME`` env var (if set) — honours an operator who pinned Soothe's home
+3. ``~/.flowjet`` (default)
+
+When ``SOOTHE_HOME`` is unset or still points at the Soothe default
+(``~/.soothe``), it is repointed at the resolved FlowJet home so config, data,
+and logs all land under one root.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_SOOTHE_HOME = str(Path.home() / ".soothe")
+_DEFAULT_FLOWJET_HOME = str(Path.home() / ".flowjet")
+
+_ALIGNED = False
+
+
+def resolve_home() -> Path:
+    """Return the shared home directory for FlowJet and Soothe.
+
+    Priority: ``FLOWJET_HOME`` > ``SOOTHE_HOME`` > ``~/.flowjet``.
+    """
+    env_fj = os.environ.get("FLOWJET_HOME")
+    if env_fj:
+        return Path(env_fj).expanduser()
+    env_soothe = os.environ.get("SOOTHE_HOME")
+    if env_soothe and env_soothe != _DEFAULT_SOOTHE_HOME:
+        return Path(env_soothe).expanduser()
+    return Path(_DEFAULT_FLOWJET_HOME).expanduser()
+
+
+def ensure_flowjet_home() -> Path:
+    """Align ``SOOTHE_HOME`` with the FlowJet home and create the logs dir.
+
+    Idempotent. Returns the resolved home path. Safe to call before any soothe
+    module is imported — and it *must* be, because ``soothe_sdk.paths`` binds
+    ``SOOTHE_HOME`` at import time.
+    """
+    global _ALIGNED
+    home = resolve_home()
+
+    # Repoint SOOTHE_HOME at the FlowJet home unless an operator has already
+    # pinned it somewhere other than the Soothe default. ``setdefault`` keeps
+    # an explicit SOOTHE_HOME that is not the default.
+    current_soothe = os.environ.get("SOOTHE_HOME")
+    if current_soothe is None or current_soothe == _DEFAULT_SOOTHE_HOME:
+        os.environ["SOOTHE_HOME"] = str(home)
+
+    # SOOTHE_DATA_DIR follows SOOTHE_HOME/data by default in soothe_sdk.paths;
+    # only set it when unset so an explicit operator override wins.
+    os.environ.setdefault("SOOTHE_DATA_DIR", str(home / "data"))
+
+    # Ensure the logs directory exists so file handlers never fail on first write.
+    (home / "logs").mkdir(parents=True, exist_ok=True)
+
+    _ALIGNED = True
+    return home
+
+
+def flowjet_home() -> Path:
+    """Return the aligned FlowJet home (aligns on first call if not yet done)."""
+    if not _ALIGNED:
+        return ensure_flowjet_home()
+    return resolve_home()
+
+
+def log_dir() -> Path:
+    """Return the log directory under the FlowJet home."""
+    return flowjet_home() / "logs"
+
+
+def cli_log_path() -> Path:
+    """Return the CLI log file path (``<home>/logs/cli.log``)."""
+    return log_dir() / "cli.log"
+
+
+def setup_file_logging(
+    *,
+    log_file: str | Path | None = None,
+    extra_logger_names: tuple[str, ...] = (),
+) -> None:
+    """Configure rotating file logging under the FlowJet home.
+
+    Delegates to ``soothe_nano.logging.setup.setup_logging`` so the FlowJet
+    logger trees share the same rotating handler, formatter, and thread-id
+    context as Soothe. The default log file is ``<home>/logs/flowjet.log``;
+    pass ``log_file`` to override (e.g. ``cli.log`` for the CLI surface).
+
+    Args:
+        log_file: Optional log file path override.
+        extra_logger_names: Additional logger tree roots (e.g. ``("flowjet",)``)
+            to attach the same file handler to.
+    """
+    ensure_flowjet_home()
+    from soothe_nano.logging.setup import setup_logging
+
+    target = str(log_file) if log_file is not None else str(log_dir() / "flowjet.log")
+    # FlowJet's own logger trees share the handler with soothe_nano's.
+    names: tuple[str, ...] = ("flowjet", *extra_logger_names)
+    setup_logging(log_file=target, extra_logger_names=names)
+
+
+__all__ = [
+    "cli_log_path",
+    "ensure_flowjet_home",
+    "flowjet_home",
+    "log_dir",
+    "resolve_home",
+    "setup_file_logging",
+]

{flowjet-2.0.3 → flowjet-2.0.4}/src/flowjet/server/__main__.py

@@ -35,6 +35,15 @@ def _create_dual_stack_socket(host: str, port: int) -> socket.socket:
 
 
 def main() -> None:
+    # Align SOOTHE_HOME with FLOWJET_HOME before any soothe import so config,
+    # data, and logs all land under ~/.flowjet. Must run before Settings() or
+    # any soothe_nano import: soothe_sdk.paths binds SOOTHE_HOME at import time.
+    from flowjet.core.home import ensure_flowjet_home, setup_file_logging
+
+    ensure_flowjet_home()
+    # Record server runs to <FLOWJET_HOME>/logs/flowjet.log by default.
+    setup_file_logging(extra_logger_names=("flowjet",))
+
     settings = Settings()
     # When the host is a wildcard (``::`` or ``0.0.0.0``), use a dual-stack
     # socket so both IPv4 and IPv6 clients can connect.  This is essential