flowjet 2.1.3__tar.gz → 2.1.4__tar.gz

{flowjet-2.1.3 → flowjet-2.1.4}/CHANGELOG.md

@@ -10,6 +10,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.4] — 2026-10-23
+
+### Added
+
+- **Resumable `ask_user` pauses via shared thread-state checkpointer.** The
+  server now persists agent thread state (LangGraph checkpoint) to a shared
+  SQLite database (WAL mode + busy_timeout) so that `ask_user` pauses survive
+  pool-worker switches and server restarts. A second turn on the same session
+  resumes the paused interrupt and delivers the user's input text as the
+  answer — no more re-asking the same question after a worker rotation. The
+  `server_checkpointer` setting (`"auto"` by default, `"off"` for legacy
+  stateless behavior) controls the policy end-to-end: Settings →
+  `ServerRuntimeBuilder` → `build_isolating_nano_backend` →
+  `AgentAdapterBase`, which opens the checkpointer once per worker, attaches
+  it at build time, and survives taint rebuilds.
+
+### Changed
+
+- **CI now enforces mypy type compliance.** A `make typecheck` (mypy) gate
+  was added to the CI pipeline, and type annotations were fixed across the
+  CLI, core, and server packages to achieve full compliance.
+
 ## [2.1.3] — 2026-10-23
 
 ### Fixed

{flowjet-2.1.3 → flowjet-2.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowjet
-Version: 2.1.3
+Version: 2.1.4
 Summary: FlowJet — agent CLI (fj) and server (ACP + OpenAI-compatible HTTP) powered by Soothe
 Project-URL: Homepage, https://github.com/caesar0301/flowjet
 Project-URL: Repository, https://github.com/caesar0301/flowjet

{flowjet-2.1.3 → flowjet-2.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flowjet"
-version = "2.1.3"
+version = "2.1.4"
 description = "FlowJet — agent CLI (fj) and server (ACP + OpenAI-compatible HTTP) powered by Soothe"
 readme = "README.md"
 license = { text = "MIT" }
@@ -102,6 +102,8 @@ python_version = "3.12"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
+# Skill-local scripts ship their own (looser) tooling; excluded from package lint.
+exclude = "src/flowjet/builtin_skills"
 
 # Any-heavy moved code; loosened until annotated.
 [[tool.mypy.overrides]]
@@ -109,6 +111,17 @@ module = ["flowjet.server.*", "flowjet.core.bridges.*"]
 disallow_untyped_defs = false
 warn_return_any = false
 
+# Local runtimes and stub-less third-party packages consumed at runtime;
+# typed via runtime contract, not via inline types.
+[[tool.mypy.overrides]]
+module = [
+    "soothe_nano.*",
+    "soothe.*",
+    "fsspec",
+    "yaml",
+]
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"

{flowjet-2.1.3 → flowjet-2.1.4}/src/flowjet/cli/agent.py

@@ -108,11 +108,9 @@ async def build_agent(
         mode = "bypass"
     configure_cli_logging(verbose=verbose)
     ensure_workspace(workspace)
-    agent = create_agent(config, CLI_PROFILE, interaction_mode=mode)
+    agent = create_agent(config, CLI_PROFILE, interaction_mode=mode, checkpointer=checkpointer)
     # Plugin imports (e.g. browser_use) may still attach root console handlers.
     silence_after_plugins(verbose=verbose)
-    if checkpointer is not None:
-        agent.graph.checkpointer = checkpointer
     return agent
 
 

{flowjet-2.1.3 → flowjet-2.1.4}/src/flowjet/cli/cli.py

@@ -16,7 +16,7 @@ import traceback
 from collections.abc import Coroutine
 from logging.handlers import RotatingFileHandler
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 from flowjet.cli import __version__
 
@@ -441,7 +441,8 @@ def _build_parser(prog: str | None = None) -> argparse.ArgumentParser:
         "-c",
         "--config",
         metavar="PATH",
-        help=_LazyHelp(_default_config_help),
+        # Lazy help keeps the heavy default-config import off -V / normal runs.
+        help=cast("str", _LazyHelp(_default_config_help)),
     )
     paths.add_argument(
         "-w",
@@ -468,7 +469,8 @@ def _build_setup_parser(prog: str | None = None) -> argparse.ArgumentParser:
         "-c",
         "--config",
         metavar="PATH",
-        help=_LazyHelp(_default_config_help),
+        # Lazy help keeps the heavy default-config import off -V / normal runs.
+        help=cast("str", _LazyHelp(_default_config_help)),
     )
     return parser
 
@@ -570,35 +572,16 @@ def run_pin_thread(thread_id: str) -> int:
 async def _detect_pending_interrupt(agent: Any, thread_id: str) -> Any:
     """Return the pending ``ask_user`` interrupt value, or ``None``.
 
-    Checks the LangGraph snapshot for the thread. When an ``ask_user``
-    interrupt is pending, its ``value`` carries the question specs; the CLI
-    can resume the run by feeding the user's answer to ``Command(resume=...)``.
+    Thin wrapper over the shared bridge helper
+    (:func:`flowjet.core.bridges.nano.interrupts.detect_pending_ask_user`) so
+    the CLI and the server surfaces apply the exact same probe. When an
+    ``ask_user`` interrupt is pending, its ``value`` carries the question
+    specs; the run resumes by feeding the user's answer to
+    ``Command(resume=...)``.
     """
-    get_state = getattr(agent, "aget_state", None)
-    if not callable(get_state):
-        return None
-    try:
-        snapshot = await get_state({"configurable": {"thread_id": thread_id}})
-    except Exception as exc:
-        # Not fatal — but explain why a pending question may be missed and a
-        # new turn started instead of resuming (visible with -v / FJ_LOG_FILE).
-        _logger.warning("thread snapshot check failed; starting a new turn: %s", exc)
-        return None
-    if snapshot is None:
-        return None
-    interrupts = getattr(snapshot, "interrupts", None) or ()
-    if not interrupts:
-        # Some snapshots nest interrupts under per-task state.
-        tasks = getattr(snapshot, "tasks", None) or ()
-        for task in tasks:
-            task_interrupts = getattr(task, "interrupts", None) or ()
-            interrupts = task_interrupts
-            break
-    for entry in interrupts:
-        value = getattr(entry, "value", None)
-        if isinstance(value, dict) and value.get("type") == "ask_user":
-            return value
-    return None
+    from flowjet.core.bridges.nano.interrupts import detect_pending_ask_user
+
+    return await detect_pending_ask_user(agent, {"configurable": {"thread_id": thread_id}})
 
 
 async def run_async(args: argparse.Namespace) -> int:

{flowjet-2.1.3 → flowjet-2.1.4}/src/flowjet/cli/doctor_cmd.py

@@ -153,7 +153,8 @@ async def _run_diagnose(
             "soothe-nano diagnose API unavailable; upgrade soothe-nano "
             "(fj doctor requires soothe-nano>=1.0.8)"
         ) from exc
-    return await diagnose(config, deep=deep, live_llm=live_llm)
+    result: list[dict[str, Any]] = await diagnose(config, deep=deep, live_llm=live_llm)
+    return result
 
 
 def _bin_version(bin_path: str) -> str | None:
@@ -174,6 +175,7 @@ def _bin_version(bin_path: str) -> str | None:
 
 def _find_chrome_executable() -> str | None:
     """Locate a Chrome/Chromium-family browser executable, or None."""
+    candidates: list[str]
     if sys.platform == "darwin":
         candidates = [
             "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",

{flowjet-2.1.3 → flowjet-2.1.4}/src/flowjet/cli/progress.py

@@ -310,7 +310,7 @@ def _abbrev_path(path: str) -> str:
     try:
         from soothe_nano.utils.formatting import convert_and_abbreviate_path
 
-        return convert_and_abbreviate_path(path)
+        return str(convert_and_abbreviate_path(path))
     except Exception:
         home = os.path.expanduser("~")
         if path.startswith(home + os.sep):

{flowjet-2.1.3 → flowjet-2.1.4}/src/flowjet/cli/setup_cmd.py

@@ -241,7 +241,7 @@ def choose_provider_interactive(providers: list[dict[str, Any]]) -> dict[str, An
 
 def resolve_config_value(value: str, *, field: str) -> str:
     """Expand ``${ENV_VAR}`` placeholders; raise if any remain unresolved."""
-    resolved = _resolve_env(value)
+    resolved = str(_resolve_env(value))
     match = _ENV_VAR_RE.search(resolved)
     if match:
         env_name = match.group(1)

{flowjet-2.1.3 → flowjet-2.1.4}/src/flowjet/core/agent/factory.py

@@ -41,6 +41,7 @@ class AgentFactory:
         interaction_mode: InteractionMode | str | None = None,
         backend: Backend | None = None,
         sandbox: Any | None = None,
+        checkpointer: Any | None = None,
     ) -> Any:
         from flowjet.core.modes import apply_profile
 
@@ -49,16 +50,18 @@ class AgentFactory:
         cfg = apply_profile(config, profile, backend=resolved)
 
         if resolved is Backend.SOOTHE:
-            return cls.create_soothe(cfg, profile, mode, sandbox=sandbox)
+            return cls.create_soothe(cfg, profile, mode, sandbox=sandbox, checkpointer=checkpointer)
 
         if profile.surface is Surface.SERVER:
             from soothe_nano import create_dual_mode_nano_agent
 
-            return create_dual_mode_nano_agent(cfg, backend=sandbox)
+            return create_dual_mode_nano_agent(cfg, backend=sandbox, checkpointer=checkpointer)
 
         from soothe_nano import create_nano_agent
 
-        return create_nano_agent(cfg, interaction_mode=mode, backend=sandbox)
+        return create_nano_agent(
+            cfg, interaction_mode=mode, backend=sandbox, checkpointer=checkpointer
+        )
 
     @staticmethod
     def soothe_builder() -> Any:
@@ -80,18 +83,33 @@ class AgentFactory:
         mode: str | None = None,
         *,
         sandbox: Any | None = None,
+        checkpointer: Any | None = None,
     ) -> Any:
         """Build a ``soothe`` (host runtime) agent for ``profile``'s surface.
 
         ``interrupt_on`` is pinned to ``{}``: the host builder otherwise injects
         HITL interrupts for mutating tools (``edit_file`` / ``write_file`` /
-        ``delete`` / ``run_command``), and FlowJet has no resume path — it
-        renders ``InterruptWaiting`` and stops, so any write would stall the run.
+        ``delete`` / ``run_command``), and FlowJet does not surface those
+        approval requests as resumable pauses — only ``ask_user`` clarifications
+        are resumed (via the checkpointer + ``Command(resume=...)``), so a
+        mutating-tool interrupt would stall the run.
+
+        ``checkpointer`` is attached at graph-compile time so both mode graphs
+        of a server-surface agent share it (a post-hoc ``graph.checkpointer``
+        assignment would only reach the default mode's lazily compiled graph).
         """
         factory = cls.soothe_builder()
         if profile.surface is Surface.SERVER:
-            return ModeRoutedSootheAgent(config, factory, sandbox=sandbox)
-        return factory(config, interaction_mode=mode, interrupt_on={}, backend=sandbox)
+            return ModeRoutedSootheAgent(
+                config, factory, sandbox=sandbox, checkpointer=checkpointer
+            )
+        return factory(
+            config,
+            interaction_mode=mode,
+            interrupt_on={},
+            backend=sandbox,
+            checkpointer=checkpointer,
+        )
 
 
 class ModeRoutedSootheAgent:
@@ -103,8 +121,10 @@ class ModeRoutedSootheAgent:
     request must never land on the ``agent`` graph. Agents are built lazily, so
     a worker that only serves ``ask`` never builds the ``agent`` graph.
 
-    Only ``astream`` is proxied: that is the whole surface the nano bridge
-    (``flowjet.core.bridges.nano.mapping``) drives.
+    Only ``astream`` and ``aget_state`` are proxied: that is the whole
+    surface the nano bridge (``flowjet.core.bridges.nano.mapping``) drives
+    — streaming a turn, and probing the thread snapshot for a pending
+    ``ask_user`` interrupt before it.
     """
 
     def __init__(
@@ -114,11 +134,13 @@ class ModeRoutedSootheAgent:
         modes: tuple[str, ...] = ("agent", "ask"),
         *,
         sandbox: Any | None = None,
+        checkpointer: Any | None = None,
     ) -> None:
         self._config = config
         self._factory = factory
         self._modes = modes
         self._sandbox = sandbox
+        self._checkpointer = checkpointer
         self._agents: dict[str, Any] = {}
 
     def _agent_for(self, mode: str) -> Any:
@@ -130,18 +152,40 @@ class ModeRoutedSootheAgent:
                 interaction_mode=resolved,
                 interrupt_on={},
                 backend=self._sandbox,
+                checkpointer=self._checkpointer,
             )
             self._agents[resolved] = agent
         return agent
 
+    def _agent_for_config(self, config: Any) -> Any:
+        """Pick the mode agent for a runnable config (mirrors ``astream``)."""
+        configurable: dict[str, Any] = {}
+        if isinstance(config, dict):
+            raw = config.get("configurable") or {}
+            if isinstance(raw, dict):
+                configurable = raw
+        mode = str(configurable.get("interaction_mode") or "agent")
+        return self._agent_for(mode)
+
     async def astream(self, payload: Any, **kwargs: Any) -> Any:
         """Proxy ``astream`` to the agent built for the request's mode."""
         config = kwargs.get("config") or {}
-        configurable = config.get("configurable") or {} if isinstance(config, dict) else {}
-        mode = str(configurable.get("interaction_mode") or "agent")
-        agent = self._agent_for(mode)
+        agent = self._agent_for_config(config)
         async for chunk in agent.astream(payload, **kwargs):
             yield chunk
 
+    async def aget_state(self, config: Any = None) -> Any:
+        """Proxy ``aget_state`` to the agent built for the config's mode.
+
+        Soft-fails to ``None`` when the mode agent cannot read graph state
+        (no checkpointer), matching ``SootheNanoAgent.aget_state`` semantics
+        so pending-interrupt probes degrade instead of raising.
+        """
+        agent = self._agent_for_config(config)
+        get_state = getattr(agent, "aget_state", None)
+        if not callable(get_state):
+            return None
+        return await get_state(config=config)
+
 
 __all__ = ["AgentFactory", "ModeRoutedSootheAgent"]

{flowjet-2.1.3 → flowjet-2.1.4}/src/flowjet/core/agent/wiring.py

@@ -8,7 +8,7 @@ delegates here. core remains server-agnostic — no imports from
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 from flowjet.core.backend_config import Backend, resolve_backend
 from flowjet.core.bridges.nano import build_isolating_nano_backend
@@ -42,6 +42,13 @@ class ServerRuntimeBuilder:
     workspace host↔guest and the adapters bind soothe-nano's sandbox backend
     at agent build time. The AgentRuntime isolation is unchanged (in-process
     thread pool).
+
+    ``checkpointer_policy`` ("auto" by default) makes each worker's adapter
+    open the shared thread-state checkpointer resolved from the config's
+    durability settings — sqlite lands on
+    ``$SOOTHE_DATA_DIR/databases/checkpoints.db``. This is what keeps one
+    ACP session's conversation continuous across turns, pool workers and
+    restarts, and what makes ``ask_user`` pauses resumable.
     """
 
     @classmethod
@@ -57,6 +64,7 @@ class ServerRuntimeBuilder:
         content_source: str | None,
         allow_external_workspace: bool,
         pool_settings: Any,
+        checkpointer_policy: str | None = "auto",
     ) -> RuntimeBackend:
         backend = resolve_backend(Surface.SERVER)
         sandbox_manager = cls.sandbox_manager(config_path)
@@ -77,10 +85,11 @@ class ServerRuntimeBuilder:
             allow_external_workspace=allow_external_workspace,
             workspace_resolver=workspace_resolver,
             sandbox_manager=sandbox_manager,
+            checkpointer_policy=checkpointer_policy,
         )
         if backend is Backend.SOOTHE:
-            return build_isolating_soothe_backend(**common)
-        return build_isolating_nano_backend(**common)
+            return cast("RuntimeBackend", build_isolating_soothe_backend(**common))
+        return cast("RuntimeBackend", build_isolating_nano_backend(**common))
 
     @classmethod
     def sandbox_manager(cls, config_path: str | None) -> ArcBoxToolSandboxManager | None:

flowjet-2.1.4/src/flowjet/core/agent/workspace.py

@@ -0,0 +1,157 @@
+"""Workspace env binding and sqlite checkpointer opening."""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from soothe_nano.utils.resolver import resolve_checkpointer
+
+logger = logging.getLogger(__name__)
+
+# Treatments of the checkpointer policy that mean "do not persist".
+_OFF_VALUES = frozenset({"", "off", "disabled", "none", "false", "0"})
+
+
+def checkpointer_policy_enabled(policy: str | None) -> bool:
+    """Whether a checkpointer policy string enables persistence."""
+    return str(policy or "").strip().lower() not in _OFF_VALUES
+
+
+class Workspaces:
+    """Bind the workspace root used by file/shell tools."""
+
+    @staticmethod
+    def ensure(workspace: Path | None = None) -> Path:
+        """Use ``workspace`` or cwd as ``SOOTHE_WORKSPACE`` for file/shell tools."""
+        root = (workspace or Path.cwd()).resolve()
+        os.environ.setdefault("SOOTHE_WORKSPACE", str(root))
+        try:
+            from soothe_nano.workspace import FrameworkFilesystem
+
+            FrameworkFilesystem.set_current_workspace(root)
+        except Exception:  # pragma: no cover - optional API surface
+            logger.debug("Could not set FrameworkFilesystem workspace", exc_info=True)
+        return root
+
+
+class Checkpointers:
+    """Side persistence: an ``AsyncSqliteSaver`` on nano's sqlite data path."""
+
+    @staticmethod
+    @asynccontextmanager
+    async def open_sqlite(config: Any) -> AsyncIterator[Any | None]:
+        """Yield an ``AsyncSqliteSaver`` using nano's default sqlite data path.
+
+        Path: ``$SOOTHE_DATA_DIR/databases/checkpoints.db`` (default
+        ``~/.soothe/data/databases/checkpoints.db``). The config copy forces
+        the sqlite backend so this works regardless of the durability settings
+        (the CLI always runs sqlite).
+        """
+        sqlite_cfg = config.model_copy(
+            update={
+                "agent": config.agent.model_copy(
+                    update={
+                        "protocols": config.agent.protocols.model_copy(
+                            update={
+                                "durability": config.agent.protocols.durability.model_copy(
+                                    update={
+                                        "backend": "sqlite",
+                                        "checkpointer": "sqlite",
+                                    }
+                                )
+                            }
+                        )
+                    }
+                )
+            }
+        )
+        result = resolve_checkpointer(sqlite_cfg)
+        db_path = _sqlite_db_path(result)
+        if not db_path:
+            logger.warning("SQLite checkpointer path unresolved; running without persistence")
+            yield None
+            return
+
+        saver = await _connect_sqlite(db_path)
+        try:
+            yield saver
+        finally:
+            await saver.conn.close()
+
+    @staticmethod
+    @asynccontextmanager
+    async def open(config: Any) -> AsyncIterator[Any | None]:
+        """Yield a checkpointer for the config's resolved durability backend.
+
+        Server-surface counterpart of :meth:`open_sqlite`: honors
+        ``agent.protocols.durability.checkpointer`` (which inherits
+        ``persistence.default_backend``), so a deployment that asks for sqlite
+        gets thread state that survives across turns, pool workers and
+        restarts. ``postgresql`` is not wired for the server surface yet — it
+        warns and yields ``None`` (no persistence) rather than failing
+        startup.
+        """
+        try:
+            backend = str(config.resolve_checkpointer_backend()).strip().lower()
+        except Exception:  # noqa: BLE001 - unknown config shape → sqlite default
+            backend = "sqlite"
+        if backend != "sqlite":
+            logger.warning(
+                "Checkpointer backend %r is not wired for the flowjet server "
+                "surface yet; thread state will not persist across turns",
+                backend,
+            )
+            yield None
+            return
+
+        result = resolve_checkpointer(config)
+        db_path = _sqlite_db_path(result)
+        if not db_path:
+            logger.warning("SQLite checkpointer path unresolved; running without persistence")
+            yield None
+            return
+
+        saver = await _connect_sqlite(db_path)
+        try:
+            yield saver
+        finally:
+            await saver.conn.close()
+
+
+def _sqlite_db_path(result: Any) -> str | None:
+    """Extract the sqlite db path from a ``resolve_checkpointer`` result."""
+    if isinstance(result, tuple):
+        _placeholder, pool_or_path = result
+        if isinstance(pool_or_path, str):
+            return pool_or_path
+    return None
+
+
+async def _connect_sqlite(db_path: str) -> Any:
+    """Open one ``AsyncSqliteSaver`` connection on ``db_path``.
+
+    WAL + busy timeout are load-bearing for the server: its thread pool opens
+    one connection per worker onto the same file, and the default rollback
+    journal would block readers behind writers and surface as
+    ``database is locked``.
+    """
+    import aiosqlite
+    from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+    from soothe_nano.utils.serde import create_soothe_serde
+
+    Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+    conn = await aiosqlite.connect(db_path)
+    await conn.execute("PRAGMA journal_mode=WAL")
+    await conn.execute("PRAGMA busy_timeout=5000")
+    checkpointer = AsyncSqliteSaver(conn, serde=create_soothe_serde())
+    await checkpointer.setup()
+    logger.debug("SQLite checkpointer ready at %s", db_path)
+    return checkpointer
+
+
+__all__ = ["Checkpointers", "Workspaces", "checkpointer_policy_enabled"]