flowjet 2.0.1__tar.gz → 2.0.3__tar.gz

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

@@ -10,6 +10,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.3] — 2026-09-18
+
+### Added
+
+- **Plan-step and middleware-phase progress in the CLI.** The nano bridge now
+  maps the host (soothe) loop's todo list and middleware phase updates into
+  step/tool progress events, so the terminal shows `Step 2/3 · Create a2.txt`
+  instead of a bare `Working` line. Late-parsing tool args refresh the status
+  line once, and `write_todos` bookkeeping is suppressed as a tool call (it
+  already drives the step line).
+
+## [2.0.2] — 2026-09-18
+
+### Added
+
+- **Duo backends — `soothe` or `soothe-nano`.** `FLOWJET_BACKEND` (CLI, default
+  `soothe`) and `FLOWJET_SERVER_BACKEND` (HTTP/ACP, default `nano`) select which
+  runtime builds the agent. `soothe` is a host layer over soothe-nano, so the
+  engine stays installed either way; the two surfaces switch independently
+  because the server needs a dual-mode agent (AGENT + ASK graphs per request),
+  which soothe does not expose — with `FLOWJET_SERVER_BACKEND=soothe` the server
+  builds one host agent per mode and routes on `interaction_mode`.
+
+### Changed
+
+- The CLI now builds its agent through the `soothe` host runtime by default
+  (host middleware, `request_plan_mode` / `ask_user` tools, configurable
+  persona). Set `FLOWJET_BACKEND=nano` for the previous behaviour.
+
 ## [2.0.1] — 2026-09-17
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowjet
-Version: 2.0.1
+Version: 2.0.3
 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,6 +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
 Provides-Extra: dev
 Requires-Dist: httpx>=0.27.0; extra == 'dev'
 Requires-Dist: mypy>=1.0.0; extra == 'dev'
@@ -78,6 +79,20 @@ fj summarize README.md
 
 Not sure your machine is ready? `fj doctor` (add `--deep`, `--live-llm`).
 
+### Backends
+
+Two runtimes can build the agent; they are switched independently per surface:
+
+| Env var | Surface | Default | Values |
+|---------|---------|---------|--------|
+| `FLOWJET_BACKEND` | CLI (`fj`) | `soothe` | `soothe`, `nano` |
+| `FLOWJET_SERVER_BACKEND` | `flowjet-server` / `fj serve` | `nano` | `soothe`, `nano` |
+
+`soothe` is the host runtime (extra middleware and tools over the same
+soothe-nano engine). The server defaults to `nano` because it needs a dual-mode
+agent — AGENT and ASK graphs selected per request — which `soothe` does not
+expose yet; on `soothe` the server builds one host agent per mode instead.
+
 ---
 
 ## CLI

{flowjet-2.0.1 → flowjet-2.0.3}/README.md

@@ -35,6 +35,20 @@ fj summarize README.md
 
 Not sure your machine is ready? `fj doctor` (add `--deep`, `--live-llm`).
 
+### Backends
+
+Two runtimes can build the agent; they are switched independently per surface:
+
+| Env var | Surface | Default | Values |
+|---------|---------|---------|--------|
+| `FLOWJET_BACKEND` | CLI (`fj`) | `soothe` | `soothe`, `nano` |
+| `FLOWJET_SERVER_BACKEND` | `flowjet-server` / `fj serve` | `nano` | `soothe`, `nano` |
+
+`soothe` is the host runtime (extra middleware and tools over the same
+soothe-nano engine). The server defaults to `nano` because it needs a dual-mode
+agent — AGENT and ASK graphs selected per request — which `soothe` does not
+expose yet; on `soothe` the server builds one host agent per mode instead.
+
 ---
 
 ## CLI

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flowjet"
-version = "2.0.1"
+version = "2.0.3"
 description = "FlowJet — agent CLI (fj) and server (ACP + OpenAI-compatible HTTP) powered by soothe-nano"
 readme = "README.md"
 license = { text = "MIT" }
@@ -29,6 +29,9 @@ classifiers = [
 # lives in the `server` extra, and `flowjet.cli` never imports it at module
 # scope (see tests/unit/test_cli_no_server_deps.py).
 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-nano>=1.2.28,<1.3.0",
 ]
 

{flowjet-2.0.1 → flowjet-2.0.3}/src/flowjet/cli/progress.py

@@ -67,6 +67,14 @@ _ACTION_LABELS: dict[str, str] = {
     "queued": "Queued",
 }
 
+# Host (soothe) loop phases surfaced as graph updates by the nano bridge.
+_STEP_PHASE_LABELS: dict[str, str] = {
+    "planned": "Planning steps",
+    "decomposed": "Decomposing task",
+    "evaluated": "Evaluating step",
+    "fanned_out": "Coordinating agents",
+}
+
 # Verb + color for well-known tools (fallback: Running / yellow)
 _TOOL_VERBS: dict[str, tuple[str, str]] = {
     "read_file": ("Reading", "yellow"),
@@ -693,6 +701,32 @@ def friendly_progress(data: dict[str, Any]) -> tuple[str, str] | None:
                 label = f"{label} · {detail}"
         return _fit(label), color
 
+    if domain == "step":
+        # Plan steps come from the agent's todo list (one event per change).
+        if "steps" in data or "todo" in data:
+            step = data.get("step")
+            steps = data.get("steps")
+            todo = _compact(data.get("todo"))
+            head = f"Step {step}/{steps}" if step and steps else "Step"
+            if todo:
+                return _fit(f"{head} · {todo}"), "blue"
+            if data.get("status") == "completed":
+                return _fit(f"Steps complete · {step}/{steps}"), "green"
+            return _fit(head), "blue"
+        label = _STEP_PHASE_LABELS.get(action) or verb
+        return _fit(label), "blue"
+
+    if event_type == "soothe.ask.requested":
+        question = _compact(data.get("question") or data.get("message"))
+        if question:
+            q_limit = _detail_budget(prefix="Preparing question · ", fraction=0.55, floor=16)
+            return _fit(f"Preparing question · {_truncate_middle(question, q_limit)}"), "magenta"
+        return _fit("Preparing question"), "magenta"
+
+    if event_type == "soothe.intake.routed":
+        name = _compact(data.get("subagent") or data.get("subagent_type") or "specialist")
+        return _fit(f"Routing · {name}"), "magenta"
+
     if domain == "skill" or "skill" in short:
         color = "blue"
         name = data.get("skill") or data.get("name") or "skill"

flowjet-2.0.3/src/flowjet/core/backend.py

@@ -0,0 +1,107 @@
+"""Backend selection — which runtime builds FlowJet's agent.
+
+FlowJet can build its agent two ways:
+
+``soothe``
+    The host runtime (``soothe.coreagent.create_soothe_agent``). ``soothe`` is a
+    layer **on top of** soothe-nano, not a replacement for it: it injects host
+    middleware (goal/step guard, decompose, eval, ask-user), host tools
+    (``request_plan_mode``, ``ask_user``) and a configurable persona over the
+    same nano agent graph.
+
+``nano``
+    soothe-nano directly (``create_nano_agent`` for the CLI,
+    ``create_dual_mode_nano_agent`` for the server).
+
+The two surfaces switch **independently**, because they do not share the same
+constraints: the CLI builds one agent per invocation, while the server needs a
+dual-mode agent (AGENT + ASK graphs selected per request) — an API soothe does
+not expose today. Hence the defaults differ:
+
+* ``FLOWJET_BACKEND`` (CLI) — default ``soothe``.
+* ``FLOWJET_SERVER_BACKEND`` (HTTP/ACP) — default ``nano``.
+
+Both accept ``soothe`` or ``nano`` (case-insensitive); anything else is a hard
+error rather than a silent fallback, so a typo can never quietly run the wrong
+runtime.
+"""
+
+from __future__ import annotations
+
+import os
+from enum import StrEnum
+
+from flowjet.core.modes import Surface
+
+CLI_BACKEND_ENV = "FLOWJET_BACKEND"
+SERVER_BACKEND_ENV = "FLOWJET_SERVER_BACKEND"
+
+
+class Backend(StrEnum):
+    """Runtime that builds the agent."""
+
+    SOOTHE = "soothe"
+    NANO = "nano"
+
+
+#: CLI builds one agent per invocation; the host runtime is the default there.
+DEFAULT_CLI_BACKEND = Backend.SOOTHE
+
+#: The server needs per-request mode switching (dual-mode agent), which soothe
+#: does not expose; it stays on nano until host dual-mode exists.
+DEFAULT_SERVER_BACKEND = Backend.NANO
+
+_BACKENDS: dict[str, Backend] = {b.value: b for b in Backend}
+
+
+def parse_backend(value: str | None, *, default: Backend, env_name: str) -> Backend:
+    """Resolve one backend value (env string → :class:`Backend`).
+
+    ``None`` and empty/whitespace values fall back to ``default``; an unknown
+    value raises ``ValueError`` naming the offending variable.
+    """
+    if value is None:
+        return default
+    token = value.strip().lower()
+    if not token:
+        return default
+    try:
+        return _BACKENDS[token]
+    except KeyError:
+        raise ValueError(
+            f"{env_name}={value!r} is not a valid backend "
+            f"(expected one of: {', '.join(sorted(_BACKENDS))})"
+        ) from None
+
+
+def resolve_backend(surface: Surface | str) -> Backend:
+    """Return the backend configured for ``surface`` (read from the env)."""
+    resolved = Surface(str(surface))
+    if resolved is Surface.SERVER:
+        return parse_backend(
+            os.environ.get(SERVER_BACKEND_ENV),
+            default=DEFAULT_SERVER_BACKEND,
+            env_name=SERVER_BACKEND_ENV,
+        )
+    return parse_backend(
+        os.environ.get(CLI_BACKEND_ENV),
+        default=DEFAULT_CLI_BACKEND,
+        env_name=CLI_BACKEND_ENV,
+    )
+
+
+def backend_for_profile(profile: object) -> Backend:
+    """Return the backend for a :class:`~flowjet.core.modes.SurfaceProfile`."""
+    return resolve_backend(getattr(profile, "surface", Surface.CLI))
+
+
+__all__ = [
+    "CLI_BACKEND_ENV",
+    "DEFAULT_CLI_BACKEND",
+    "DEFAULT_SERVER_BACKEND",
+    "SERVER_BACKEND_ENV",
+    "Backend",
+    "backend_for_profile",
+    "parse_backend",
+    "resolve_backend",
+]

flowjet-2.0.3/src/flowjet/core/bootstrap.py

@@ -0,0 +1,310 @@
+"""Single bootstrap shared by the CLI and the server.
+
+Both surfaces used to build their agent separately (``fj_ai.agent.build_agent``
+and ``flowjet_server.bridges.nano.adapter.create_nano_agent_instance``), with
+different constructors and contradictory security defaults. This module is the
+one place where a ``SootheConfig`` is loaded, profiled and turned into an agent.
+
+Which runtime builds that agent is decided by :mod:`flowjet.core.backend`
+(``soothe`` host runtime or ``soothe-nano``), per surface.
+"""
+
+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.config import SOOTHE_HOME, SootheConfig
+from soothe_nano.resolve import resolve_checkpointer
+
+from flowjet.core.backend import Backend, resolve_backend
+from flowjet.core.modes import (
+    CLI_PROFILE,
+    InteractionMode,
+    Surface,
+    SurfaceProfile,
+    require_mode,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Builtin skills
+# ---------------------------------------------------------------------------
+
+_REGISTERED = False
+
+# Skills belong to the distribution, not to either surface: both the CLI and
+# the server expose the same FlowJet skill set.
+BUILTIN_SKILLS_DIR = Path(__file__).resolve().parents[1] / "builtin_skills"
+
+# FlowJet additions on top of soothe-nano's DEFAULT_CORE_SKILL_NAMES.
+FJ_CORE_SKILL_NAMES: tuple[str, ...] = ()
+
+
+def default_core_skill_names() -> list[str]:
+    """Nano default core skills plus FlowJet workflow skills."""
+    from soothe_nano.skills.registry import DEFAULT_CORE_SKILL_NAMES
+
+    return sorted(DEFAULT_CORE_SKILL_NAMES | {n.lower() for n in FJ_CORE_SKILL_NAMES})
+
+
+def register_flowjet_builtin_skills() -> None:
+    """Register ``flowjet/builtin_skills`` as a soothe-nano builtin skill root.
+
+    Idempotent — safe to call from either surface and from pool worker threads.
+    """
+    global _REGISTERED
+    if _REGISTERED:
+        return
+    if not BUILTIN_SKILLS_DIR.is_dir():
+        return
+    from soothe_nano.skills import register_builtin_skill_root
+
+    register_builtin_skill_root(BUILTIN_SKILLS_DIR, source="builtin")
+    _REGISTERED = True
+
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+
+def default_config_path() -> Path:
+    """Return ``~/.soothe/config/nano.yml`` (respects ``SOOTHE_HOME``)."""
+    return SOOTHE_HOME / "config" / "nano.yml"
+
+
+def load_config(
+    config_path: str | Path | None = None,
+    *,
+    backend: Backend | None = None,
+) -> Any:
+    """Load a ``SootheConfig`` for ``backend``, or bootstrap from env when missing.
+
+    The config class follows the backend: ``soothe`` loads the *host*
+    ``soothe.config.SootheConfig`` (a superset of nano's — the host agent reads
+    host-owned fields such as ``agent.loop`` / ``agent.clarification`` that nano's
+    config does not define), ``nano`` loads ``soothe_nano.config.SootheConfig``.
+
+    Resolution order:
+    1. Explicit ``config_path``
+    2. ``SOOTHE_HOME / config / nano.yml`` (default ``~/.soothe/config/nano.yml``)
+    3. Zero-config ``SootheConfig()`` from ``OPENAI_API_KEY`` / ``ANTHROPIC_API_KEY``
+
+    On the ``soothe`` backend, a sibling ``soothe.yml`` (host-owned keys) is
+    composed over ``nano.yml`` when present.
+    """
+    backend = backend or resolve_backend(Surface.CLI)
+    path = Path(config_path).expanduser() if config_path else default_config_path()
+    if path.is_file():
+        return _load_config_file(path, backend)
+    if config_path is not None:
+        raise FileNotFoundError(f"Config not found: {path}")
+    return default_config(backend)
+
+
+def default_config(backend: Backend) -> Any:
+    """Zero-config ``SootheConfig`` for ``backend`` (env-derived providers)."""
+    if backend is Backend.SOOTHE:
+        from soothe.config import SootheConfig as HostSootheConfig
+
+        return HostSootheConfig()
+    return SootheConfig()
+
+
+def _load_config_file(path: Path, backend: Backend) -> Any:
+    """Parse ``path`` into the config class owned by ``backend``."""
+    if backend is Backend.SOOTHE:
+        from soothe.config import SootheConfig as HostSootheConfig
+
+        host_path = path.with_name("soothe.yml")
+        if host_path.is_file():
+            return HostSootheConfig.from_split_yaml_files(
+                nano_path=str(path), soothe_path=str(host_path)
+            )
+        return HostSootheConfig.from_yaml_file(str(path))
+    return SootheConfig.from_yaml_file(str(path))
+
+
+# ---------------------------------------------------------------------------
+# Workspace / checkpointer
+# ---------------------------------------------------------------------------
+
+
+def ensure_workspace(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
+
+
+@asynccontextmanager
+async def open_sqlite_checkpointer(config: Any) -> AsyncIterator[Any | None]:
+    """Yield an ``AsyncSqliteSaver`` using nano's default sqlite data path.
+
+    Path: ``$SOOTHE_DATA_DIR/soothe_checkpoints.db`` (default ``~/.soothe/data/``).
+    """
+    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: str | None = None
+    if isinstance(result, tuple):
+        _placeholder, pool_or_path = result
+        if isinstance(pool_or_path, str):
+            db_path = pool_or_path
+
+    if not db_path:
+        logger.warning("SQLite checkpointer path unresolved; running without persistence")
+        yield None
+        return
+
+    import aiosqlite
+    from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+    from soothe_sdk.utils.serde import create_soothe_serde
+
+    Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+    conn = await aiosqlite.connect(db_path)
+    checkpointer = AsyncSqliteSaver(conn, serde=create_soothe_serde())
+    await checkpointer.setup()
+    logger.debug("SQLite checkpointer ready at %s", db_path)
+    try:
+        yield checkpointer
+    finally:
+        await conn.close()
+
+
+# ---------------------------------------------------------------------------
+# Agent construction
+# ---------------------------------------------------------------------------
+
+
+def create_agent(
+    config: Any,
+    profile: SurfaceProfile = CLI_PROFILE,
+    *,
+    interaction_mode: InteractionMode | str | None = None,
+    backend: Backend | None = None,
+) -> Any:
+    """Build an agent for ``profile``'s surface on the selected backend.
+
+    The backend comes from ``FLOWJET_BACKEND`` (CLI) / ``FLOWJET_SERVER_BACKEND``
+    (server) unless ``backend`` is passed explicitly — see
+    :mod:`flowjet.core.backend`.
+
+    The server uses a dual-mode agent and supplies the interaction mode per
+    request through the LangGraph ``configurable`` dict; the CLI resolves the
+    mode up front and passes it to the single-mode constructor.
+    """
+    from flowjet.core.modes import apply_profile
+
+    mode = require_mode(interaction_mode, profile)
+    resolved = backend or resolve_backend(profile.surface)
+    cfg = apply_profile(config, profile, backend=resolved)
+
+    if resolved is Backend.SOOTHE:
+        return create_soothe_agent(cfg, profile, mode)
+
+    if profile.surface is Surface.SERVER:
+        from soothe_nano import create_dual_mode_nano_agent
+
+        return create_dual_mode_nano_agent(cfg)
+
+    from soothe_nano import create_nano_agent
+
+    return create_nano_agent(cfg, interaction_mode=mode)
+
+
+def soothe_agent_factory() -> Any:
+    """Return ``soothe.coreagent.create_soothe_agent`` (imported lazily).
+
+    Kept as a seam so the host runtime is imported only when it is actually
+    selected — the ``nano`` backend never pays for it, and tests patch this
+    instead of building a real host agent.
+    """
+    from soothe.coreagent import create_soothe_agent
+
+    return create_soothe_agent
+
+
+def create_soothe_agent(
+    config: Any,
+    profile: SurfaceProfile = CLI_PROFILE,
+    mode: str | 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.
+    """
+    factory = soothe_agent_factory()
+    if profile.surface is Surface.SERVER:
+        return ModeRoutedSootheAgent(config, factory)
+    return factory(config, interaction_mode=mode, interrupt_on={})
+
+
+class ModeRoutedSootheAgent:
+    """Route one server request to the host agent built for its mode.
+
+    soothe has no dual-mode API (nano's ``create_dual_mode_nano_agent`` has no
+    host equivalent), so the server surface keeps one host agent per allowed
+    mode and picks it from ``configurable["interaction_mode"]`` — an ``ask``
+    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.
+    """
+
+    def __init__(
+        self,
+        config: Any,
+        factory: Any,
+        modes: tuple[str, ...] = ("agent", "ask"),
+    ) -> None:
+        self._config = config
+        self._factory = factory
+        self._modes = modes
+        self._agents: dict[str, Any] = {}
+
+    def _agent_for(self, mode: str) -> Any:
+        resolved = mode if mode in self._modes else "agent"
+        agent = self._agents.get(resolved)
+        if agent is None:
+            agent = self._factory(self._config, interaction_mode=resolved, interrupt_on={})
+            self._agents[resolved] = agent
+        return agent
+
+    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)
+        async for chunk in agent.astream(payload, **kwargs):
+            yield chunk

{flowjet-2.0.1 → flowjet-2.0.3}/src/flowjet/core/bridges/nano/adapter.py

@@ -22,15 +22,16 @@ def create_nano_agent_instance(config_path: str | Path | None = None) -> Any:
     :data:`flowjet.core.modes.SERVER_PROFILE`; they are applied by the shared
     bootstrap rather than re-implemented here.
     """
-    from flowjet.core.bootstrap import create_agent, load_config
+    from flowjet.core.backend import resolve_backend
+    from flowjet.core.bootstrap import create_agent, default_config, load_config
+    from flowjet.core.modes import Surface
 
+    backend = resolve_backend(Surface.SERVER)
     try:
-        config = load_config(config_path)
+        config = load_config(config_path, backend=backend)
     except FileNotFoundError:
-        from soothe_nano.config import SootheConfig
-
-        config = SootheConfig()
-    return create_agent(config, SERVER_PROFILE)
+        config = default_config(backend)
+    return create_agent(config, SERVER_PROFILE, backend=backend)
 
 
 class NanoAgentAdapter: