Merge branch 'main' into fix-skill-archive-symlink-traversal

lib/cli/tests/deploy/test_archive.py

@@ -132,7 +132,7 @@ def test_create_project_zip_excludes_symlinked_files(tmp_path: Path):
     assert names == {"pyproject.toml"}
 
 
-def test_create_project_zip_adds_json_project_wrapper(tmp_path: Path):
+def test_create_project_zip_preserves_json_project_shape(tmp_path: Path):
     (tmp_path / "pyproject.toml").write_text(
         """
 [project]
@@ -157,8 +157,6 @@ type = "crew"
     try:
         with zipfile.ZipFile(archive_path) as archive:
             names = set(archive.namelist())
-            crew_py = archive.read("src/json_crew/crew.py").decode()
-            main_py = archive.read("src/json_crew/main.py").decode()
             pyproject = archive.read("pyproject.toml").decode()
     finally:
         archive_path.unlink(missing_ok=True)
@@ -166,18 +164,50 @@ type = "crew"
     assert "uv.lock" not in names
     assert "crew.jsonc" in names
     assert "agents/researcher.jsonc" in names
-    assert "src/json_crew/__init__.py" in names
-    assert "src/json_crew/crew.py" in names
-    assert "src/json_crew/main.py" in names
-    assert "src/json_crew/config/agents.yaml" in names
-    assert "src/json_crew/config/tasks.yaml" in names
-    assert "load_crew(_crew_path())" in crew_py
-    assert "JsonCrew" in crew_py
-    assert "from json_crew.crew import JsonCrew" in main_py
-    assert "run_crew = \"json_crew.main:run\"" in pyproject
+    assert all(not name.startswith("src/") for name in names)
+    assert "run_crew" not in pyproject
+    assert "json_crew =" not in pyproject
+    assert "[project.scripts]" not in pyproject
 
 
-def test_create_project_zip_updates_existing_json_project_scripts(tmp_path: Path):
+def test_create_project_zip_keeps_json_project_root_shape(tmp_path: Path):
+    (tmp_path / "pyproject.toml").write_text(
+        """
+[project]
+name = "json_crew"
+version = "0.1.0"
+dependencies = ["crewai[tools]==1.14.8a1"]
+
+[tool.crewai]
+type = "crew"
+""".strip()
+        + "\n"
+    )
+    (tmp_path / "uv.lock").write_text("# lock\n")
+    (tmp_path / "agents").mkdir()
+    (tmp_path / "agents" / "foo.jsonc").write_text("{}\n")
+    (tmp_path / "crew.jsonc").write_text("{}\n")
+
+    archive_path = create_project_zip("json_crew", project_dir=tmp_path)
+    try:
+        with zipfile.ZipFile(archive_path) as archive:
+            names = set(archive.namelist())
+            pyproject = archive.read("pyproject.toml").decode()
+    finally:
+        archive_path.unlink(missing_ok=True)
+
+    assert names == {
+        "agents/foo.jsonc",
+        "crew.jsonc",
+        "pyproject.toml",
+        "uv.lock",
+    }
+    assert "run_crew" not in pyproject
+    assert "json_crew =" not in pyproject
+    assert "[project.scripts]" not in pyproject
+
+
+def test_create_project_zip_does_not_rewrite_json_project_scripts(tmp_path: Path):
     (tmp_path / "pyproject.toml").write_text(
         """
 [project]
@@ -203,14 +233,10 @@ type = "crew"
     finally:
         archive_path.unlink(missing_ok=True)
 
-    assert 'json_crew = "json_crew.main:run"' in pyproject
-    assert 'run_crew = "json_crew.main:run"' in pyproject
-    assert 'train = "json_crew.main:train"' in pyproject
-    assert 'replay = "json_crew.main:replay"' in pyproject
-    assert 'test = "json_crew.main:test"' in pyproject
-    assert 'run_with_trigger = "json_crew.main:run_with_trigger"' in pyproject
+    assert 'json_crew = "old.module:run"' in pyproject
+    assert 'run_crew = "old.module:run"' in pyproject
     assert 'custom = "custom.module:main"' in pyproject
-    assert "old.module:run" not in pyproject
+    assert pyproject.count("[project.scripts]") == 1
     assert "[tool.crewai]" in pyproject
 
 
@@ -221,7 +247,7 @@ type = "crew"
         '[tool]\ncrewai = "invalid"\n',
     ],
 )
-def test_create_project_zip_adds_json_wrapper_for_malformed_tool_config(
+def test_create_project_zip_preserves_json_project_with_malformed_tool_config(
     tmp_path: Path, tool_config: str
 ):
     (tmp_path / "pyproject.toml").write_text(
@@ -244,12 +270,13 @@ version = "0.1.0"
     finally:
         archive_path.unlink(missing_ok=True)
 
-    assert "src/json_crew/crew.py" in names
-    assert "src/json_crew/main.py" in names
-    assert "run_crew = \"json_crew.main:run\"" in pyproject
+    assert names == {"crew.jsonc", "pyproject.toml"}
+    assert "run_crew" not in pyproject
+    assert "json_crew =" not in pyproject
+    assert "[project.scripts]" not in pyproject
 
 
-def test_create_project_zip_rejects_empty_normalized_package_name(tmp_path: Path):
+def test_create_project_zip_accepts_json_project_without_package_name(tmp_path: Path):
     (tmp_path / "pyproject.toml").write_text(
         """
 [project]
@@ -263,8 +290,15 @@ type = "crew"
     )
     (tmp_path / "crew.jsonc").write_text("{}\n")
 
-    with pytest.raises(
-        ValueError,
-        match=r"Could not derive a valid Python package name",
-    ):
-        create_project_zip("invalid", project_dir=tmp_path)
+    archive_path = create_project_zip("invalid", project_dir=tmp_path)
+    try:
+        with zipfile.ZipFile(archive_path) as archive:
+            names = set(archive.namelist())
+            pyproject = archive.read("pyproject.toml").decode()
+    finally:
+        archive_path.unlink(missing_ok=True)
+
+    assert names == {"crew.jsonc", "pyproject.toml"}
+    assert "run_crew" not in pyproject
+    assert "json_crew =" not in pyproject
+    assert "[project.scripts]" not in pyproject

lib/cli/tests/deploy/test_validate.py

@@ -200,6 +200,41 @@ def test_json_runtime_fields_are_deploy_errors(tmp_path: Path) -> None:
     assert "runtime-only" in finding.detail
 
 
+def test_json_crew_requires_agents_dir_without_classic_errors(tmp_path: Path) -> None:
+    _scaffold_json_crew(tmp_path)
+    for path in (tmp_path / "agents").iterdir():
+        path.unlink()
+    (tmp_path / "agents").rmdir()
+
+    v = DeployValidator(project_root=tmp_path)
+    v.run()
+
+    codes = _codes(v)
+    assert "missing_agents_dir" in codes
+    assert "missing_src_dir" not in codes
+    assert "missing_crew_py" not in codes
+    assert "missing_agents_yaml" not in codes
+    assert "missing_tasks_yaml" not in codes
+
+
+def test_json_crew_reports_project_metadata_before_invalid_json(
+    tmp_path: Path,
+) -> None:
+    _scaffold_json_crew(tmp_path)
+    (tmp_path / "pyproject.toml").unlink()
+    (tmp_path / "uv.lock").unlink()
+    (tmp_path / "crew.jsonc").write_text('{"agents": ["researcher"], "tasks": []}\n')
+
+    v = DeployValidator(project_root=tmp_path)
+    v.run()
+
+    codes = _codes(v)
+    assert "missing_pyproject" in codes
+    assert "missing_lockfile" in codes
+    assert "invalid_crew_json" in codes
+    assert "missing_src_dir" not in codes
+
+
 def test_missing_pyproject_errors(tmp_path: Path) -> None:
     v = _run_without_import_check(tmp_path)
     assert "missing_pyproject" in _codes(v)

lib/cli/tests/test_cli.py

@@ -12,6 +12,7 @@ from crewai_cli.cli import (
     deploy_remove,
     deply_status,
     flow_add_crew,
+    flow_run,
     login,
     reset_memories,
     run,
@@ -126,38 +127,75 @@ def test_run_uses_project_runner_by_default(run_crew, runner):
     result = runner.invoke(run)
 
     assert result.exit_code == 0
-    run_crew.assert_called_once_with(trained_agents_file=None)
+    run_crew.assert_called_once_with(
+        trained_agents_file=None,
+        definition=None,
+        inputs=None,
+    )
     assert "experimental" not in result.output.lower()
 
 
-@mock.patch("crewai_cli.cli.run_flow_definition")
-def test_run_with_definition_uses_definition_runner(run_flow_definition, runner):
+@mock.patch("crewai_cli.cli.run_crew")
+def test_run_with_definition_uses_project_runner(run_crew, runner):
     result = runner.invoke(
         run,
         ["--definition", "flow.yaml", "--inputs", '{"topic":"AI"}'],
     )
 
     assert result.exit_code == 0
-    assert (
-        "Warning: `crewai run --definition` is experimental and may change without notice."
-        in result.output
-    )
-    run_flow_definition.assert_called_once_with(
-        definition="flow.yaml", inputs='{"topic":"AI"}'
+    run_crew.assert_called_once_with(
+        trained_agents_file=None,
+        definition="flow.yaml",
+        inputs='{"topic":"AI"}',
     )
 
 
 @mock.patch("crewai_cli.cli.run_crew")
-@mock.patch("crewai_cli.cli.run_flow_definition")
-def test_run_rejects_inputs_without_definition(run_flow_definition, run_crew, runner):
+def test_run_rejects_inputs_without_definition(run_crew, runner):
     result = runner.invoke(run, ["--inputs", '{"topic":"AI"}'])
 
     assert result.exit_code == 2
     assert "Error: --inputs requires --definition" in result.output
-    run_flow_definition.assert_not_called()
     run_crew.assert_not_called()
 
 
+@mock.patch("crewai_cli.cli.run_crew")
+def test_run_rejects_filename_with_definition(run_crew, runner):
+    result = runner.invoke(run, ["--definition", "flow.yaml", "--filename", "x.pkl"])
+
+    assert result.exit_code == 2
+    assert "Error: --filename can only be used when running crews" in result.output
+    run_crew.assert_not_called()
+
+
+@mock.patch("crewai_cli.cli.run_crew")
+def test_run_passes_filename_to_project_runner(run_crew, runner):
+    result = runner.invoke(run, ["--filename", "trained.pkl"])
+
+    assert result.exit_code == 0
+    run_crew.assert_called_once_with(
+        trained_agents_file="trained.pkl",
+        definition=None,
+        inputs=None,
+    )
+
+
+@mock.patch("crewai_cli.cli.run_crew")
+def test_flow_kickoff_is_deprecated_and_uses_run_path(run_crew, runner):
+    result = runner.invoke(flow_run)
+
+    assert result.exit_code == 0
+    run_crew.assert_called_once_with(
+        trained_agents_file=None,
+        definition=None,
+        inputs=None,
+    )
+    assert (
+        "The command 'crewai flow kickoff' is deprecated. Use 'crewai run' instead."
+        in result.output
+    )
+
+
 @mock.patch("crewai_cli.create_json_crew.create_json_crew")
 def test_create_crew_in_dmn_mode_skips_provider_prompts(create_json_crew, runner):
     result = runner.invoke(create, ["crew", "DMN Crew"], env={"CREWAI_DMN": "True"})
@@ -166,6 +204,23 @@ def test_create_crew_in_dmn_mode_skips_provider_prompts(create_json_crew, runner
     create_json_crew.assert_called_once_with("DMN Crew", None, True)
 
 
+@mock.patch("crewai_cli.create_flow.create_flow")
+def test_create_flow_declarative_uses_declarative_scaffold(create_flow, runner):
+    result = runner.invoke(create, ["flow", "My Flow", "--declarative"])
+
+    assert result.exit_code == 0
+    create_flow.assert_called_once_with("My Flow", declarative=True)
+
+
+@mock.patch("crewai_cli.create_json_crew.create_json_crew")
+def test_create_crew_rejects_declarative_flag(create_json_crew, runner):
+    result = runner.invoke(create, ["crew", "My Crew", "--declarative"])
+
+    assert result.exit_code == 2
+    assert "--declarative can only be used with flow projects" in result.output
+    create_json_crew.assert_not_called()
+
+
 def test_create_requires_type_in_dmn_mode(runner):
     result = runner.invoke(create, env={"CREWAI_DMN": "True"})
 

lib/cli/tests/test_create_crew.py

@@ -5,7 +5,10 @@ from pathlib import Path
 from unittest import mock
 
 import pytest
+import tomli
 from click.testing import CliRunner
+from packaging.requirements import Requirement
+from packaging.version import Version
 import crewai_cli.create_json_crew as json_crew
 import crewai_cli.tui_picker as tui_picker
 from crewai_cli.create_crew import create_crew, create_folder_structure
@@ -709,8 +712,34 @@ def test_json_create_provider_preselects_default_model(tmp_path, monkeypatch):
         default_llm="openai/gpt-5.5",
     )
     assert (tmp_path / "json_crew" / "crew.jsonc").exists()
+    assert not (tmp_path / "json_crew" / "src").exists()
     assert not (tmp_path / "json_crew" / "tests").exists()
     assert not (tmp_path / "json_crew" / "config.jsonc").exists()
+    generated_paths = {
+        path.relative_to(tmp_path / "json_crew").as_posix()
+        for path in (tmp_path / "json_crew").rglob("*")
+        if path.is_file()
+    }
+    assert not any(
+        path.endswith("/crew.py") or path == "crew.py" for path in generated_paths
+    )
+    assert not any(
+        path.endswith("/agents.yaml") or path == "agents.yaml"
+        for path in generated_paths
+    )
+    assert not any(
+        path.endswith("/tasks.yaml") or path == "tasks.yaml"
+        for path in generated_paths
+    )
+    assert not any(path.startswith("src/") for path in generated_paths)
+
+    pyproject = tomli.loads((tmp_path / "json_crew" / "pyproject.toml").read_text())
+    dependency = pyproject["project"]["dependencies"][0]
+    assert dependency == "crewai[tools]==1.14.8a1"
+    assert Version("1.14.8a1") in Requirement(dependency).specifier
+    assert pyproject["tool"]["hatch"]["build"]["targets"]["wheel"][
+        "only-include"
+    ] == ["agents", "crew.jsonc", "tools", "knowledge", "skills"]
 
     crew_template = (tmp_path / "json_crew" / "crew.jsonc").read_text()
     assert (
@@ -838,7 +867,7 @@ def test_json_create_dmn_mode_uses_non_interactive_defaults(tmp_path, monkeypatc
     crew_template = (project_root / "crew.jsonc").read_text()
     agent_template = (project_root / "agents" / "researcher.jsonc").read_text()
 
-    assert '"memory": false' in crew_template
+    assert '"memory": true' in crew_template
     assert '"description": "Research current AI trends and write a concise summary."' in (
         crew_template
     )

lib/cli/tests/test_create_flow.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from click.testing import CliRunner
+from pytest import MonkeyPatch
+import tomli
+
+from crewai_cli.cli import crewai
+from crewai_cli.create_flow import create_flow
+
+
+def test_create_flow_declarative_project_can_run(
+    tmp_path: Path, monkeypatch: MonkeyPatch
+):
+    monkeypatch.chdir(tmp_path)
+    create_flow("Research Flow", declarative=True)
+
+    project_root = tmp_path / "research_flow"
+    assert project_root.is_dir()
+
+    pyproject = tomli.loads(
+        (project_root / "pyproject.toml").read_text(encoding="utf-8")
+    )
+    assert pyproject["project"]["name"] == "research_flow"
+    assert pyproject["project"]["requires-python"]
+    assert pyproject["project"]["dependencies"]
+    assert (project_root / pyproject["tool"]["crewai"]["definition"]).is_file()
+
+    monkeypatch.chdir(project_root)
+    result = CliRunner().invoke(crewai, ["run"], env={"UV_RUN_RECURSION_DEPTH": "1"})
+
+    assert result.exit_code == 0
+    assert "Running the Flow" not in result.output
+    assert "AI agents" in result.output

lib/cli/tests/test_crew_run_tui.py

@@ -4,6 +4,11 @@ import time
 import pytest
 
 from crewai.events.event_bus import crewai_event_bus
+from crewai.events.types.memory_events import (
+    MemorySaveCompletedEvent,
+    MemorySaveFailedEvent,
+    MemorySaveStartedEvent,
+)
 from crewai.events.types.observation_events import (
     GoalAchievedEarlyEvent,
     PlanRefinementEvent,
@@ -21,7 +26,12 @@ from crewai.events.types.tool_usage_events import (
 )
 from crewai_cli.command import AuthenticationRequiredError
 from crewai_cli import run_crew
-from crewai_cli.crew_run_tui import CrewRunApp
+from crewai_cli.crew_run_tui import (
+    CrewRunApp,
+    _LOG_ARGS_TEXT_LIMIT,
+    _LOG_RESULT_TEXT_LIMIT,
+    _LOG_TRUNCATION_SUFFIX,
+)
 
 
 def _app_with_plan() -> CrewRunApp:
@@ -116,6 +126,52 @@ def test_chain_deploy_does_not_login_for_deploy_exit(monkeypatch, capsys) -> Non
     assert "Deploy failed with exit code 42" in capsys.readouterr().out
 
 
+def test_conversation_turn_done_records_assistant_message() -> None:
+    class RawResult:
+        raw = "hello from the flow"
+
+    app = CrewRunApp(conversational=True)
+    app._conversation_turn_in_progress = True
+    app._enable_conversation_input = lambda: None  # type: ignore[method-assign]
+    app._tick = lambda: None  # type: ignore[method-assign]
+    app._scroll_to_result = lambda: None  # type: ignore[method-assign]
+
+    app._on_conversation_turn_done(RawResult())
+
+    assert app._conversation_messages == [("assistant", "hello from the flow")]
+    assert app._conversation_turn_in_progress is False
+    assert app._status == "chatting"
+    assert isinstance(app._crew_result, RawResult)
+
+
+@pytest.mark.asyncio
+async def test_conversation_input_submits_turn() -> None:
+    class FakeFlow:
+        defer_trace_finalization = False
+
+        def handle_turn(self, message: str) -> str:
+            return f"reply: {message}"
+
+        def finalize_session_traces(self) -> None:
+            pass
+
+    app = CrewRunApp(crew_name="Demo", conversational=True)
+    app._flow = FakeFlow()
+
+    async with app.run_test() as pilot:
+        await pilot.click("#conversation-input")
+        await pilot.press("h", "i", "enter")
+        for _ in range(50):
+            await pilot.pause(0.05)
+            if app._conversation_messages[-1:] == [("assistant", "reply: hi")]:
+                break
+
+    assert app._conversation_messages == [
+        ("user", "hi"),
+        ("assistant", "reply: hi"),
+    ]
+
+
 def test_plan_step_status_updates_only_the_explicit_step() -> None:
     app = _app_with_plan()
 
@@ -335,6 +391,396 @@ def test_internal_reasoning_function_call_is_hidden_from_activity_log() -> None:
     assert app._current_task_steps == []
 
 
+def test_memory_save_events_are_shown_in_activity_log() -> None:
+    app = _app_with_plan()
+    app._current_task_idx = 1
+    app._subscribe()
+    try:
+        _emit_event(
+            MemorySaveStartedEvent(
+                value="2 memories (background)",
+                metadata={},
+                source_type="unified_memory",
+            )
+        )
+        _emit_event(
+            MemorySaveCompletedEvent(
+                value="2 memories saved",
+                metadata={},
+                save_time_ms=123,
+                source_type="unified_memory",
+            )
+        )
+    finally:
+        app._unsubscribe()
+
+    assert len(app._log_entries) == 1
+    assert app._log_entries[0]["tool_name"] == "memory_save"
+    assert app._log_entries[0]["status"] == "success"
+    assert app._log_entries[0]["args"] == "2 memories (background)"
+    assert app._log_entries[0]["result"] == "2 memories saved"
+    assert app._log_entries[0]["error"] is None
+    assert app._log_entries[0]["duration"] == 0.123
+    assert app._log_entries[0]["task_idx"] == 1
+
+
+def test_nested_memory_save_event_is_hidden_for_save_to_memory_tool() -> None:
+    app = _app_with_plan()
+    app._subscribe()
+    try:
+        tool_args = {"contents": ["Fact to remember."]}
+        _emit_event(
+            ToolUsageStartedEvent(
+                tool_name="save_to_memory",
+                tool_args=tool_args,
+            )
+        )
+        _emit_event(
+            MemorySaveStartedEvent(
+                value="Fact to remember.",
+                metadata={},
+                source_type="unified_memory",
+            )
+        )
+        _emit_event(
+            MemorySaveCompletedEvent(
+                value="Fact to remember.",
+                metadata={},
+                save_time_ms=123,
+                source_type="unified_memory",
+            )
+        )
+        now = datetime.now()
+        _emit_event(
+            ToolUsageFinishedEvent(
+                tool_name="save_to_memory",
+                tool_args=tool_args,
+                started_at=now,
+                finished_at=now,
+                output="Saved to memory.",
+            )
+        )
+    finally:
+        app._unsubscribe()
+
+    assert len(app._log_entries) == 1
+    assert app._log_entries[0]["tool_name"] == "save_to_memory"
+    assert app._log_entries[0]["status"] == "success"
+    assert app._log_entries[0]["result"] == "Saved to memory."
+
+
+def test_memory_save_failure_is_shown_in_activity_log() -> None:
+    app = _app_with_plan()
+    app._subscribe()
+    try:
+        _emit_event(
+            MemorySaveStartedEvent(
+                value="background save",
+                metadata={},
+                source_type="unified_memory",
+            )
+        )
+        _emit_event(
+            MemorySaveFailedEvent(
+                value="background save",
+                metadata={},
+                error="embedding connection failed",
+                source_type="unified_memory",
+            )
+        )
+    finally:
+        app._unsubscribe()
+
+    assert app._log_entries[0]["tool_name"] == "memory_save"
+    assert app._log_entries[0]["status"] == "error"
+    assert app._log_entries[0]["error"] == "embedding connection failed"
+    assert app._log_expanded == {0}
+
+
+def test_memory_save_completion_updates_timed_out_row() -> None:
+    app = _app_with_plan()
+    app._subscribe()
+    try:
+        _emit_event(
+            MemorySaveStartedEvent(
+                value="9 memories (background)",
+                metadata={},
+                source_type="unified_memory",
+            )
+        )
+
+        app._log_entries[0]["status"] = "timeout"
+        app._log_entries[0]["error"] = "No result received before crew completed"
+        app._log_entries[0]["duration"] = 8.3
+
+        _emit_event(
+            MemorySaveCompletedEvent(
+                value="9 memories saved",
+                metadata={},
+                save_time_ms=8300,
+                source_type="unified_memory",
+            )
+        )
+    finally:
+        app._unsubscribe()
+
+    assert len(app._log_entries) == 1
+    assert app._log_entries[0]["tool_name"] == "memory_save"
+    assert app._log_entries[0]["status"] == "success"
+    assert app._log_entries[0]["result"] == "9 memories saved"
+    assert app._log_entries[0]["error"] is None
+    assert app._log_entries[0]["duration"] == 8.3
+
+
+def test_memory_save_completion_with_unmatched_id_does_not_update_running_row() -> None:
+    app = _app_with_plan()
+    app._subscribe()
+    try:
+        _emit_event(
+            MemorySaveStartedEvent(
+                value="first background save",
+                metadata={},
+                source_type="unified_memory",
+                parent_event_id="manual-parent",
+            )
+        )
+        _emit_event(
+            MemorySaveStartedEvent(
+                value="second background save",
+                metadata={},
+                source_type="unified_memory",
+                parent_event_id="manual-parent",
+            )
+        )
+
+        _emit_event(
+            MemorySaveCompletedEvent(
+                value="orphan save completed",
+                metadata={},
+                save_time_ms=2800,
+                source_type="unified_memory",
+                parent_event_id="manual-parent",
+                started_event_id="missing-memory-save-start",
+            )
+        )
+    finally:
+        app._unsubscribe()
+
+    assert [entry["status"] for entry in app._log_entries] == [
+        "running",
+        "running",
+        "success",
+    ]
+    assert app._log_entries[0]["args"] == "first background save"
+    assert app._log_entries[1]["args"] == "second background save"
+    assert app._log_entries[2]["result"] == "orphan save completed"
+    assert app._log_entries[2]["started_event_id"] == "missing-memory-save-start"
+
+
+def test_memory_save_failure_with_unmatched_id_does_not_update_running_row() -> None:
+    app = _app_with_plan()
+    app._subscribe()
+    try:
+        _emit_event(
+            MemorySaveStartedEvent(
+                value="first background save",
+                metadata={},
+                source_type="unified_memory",
+                parent_event_id="manual-parent",
+            )
+        )
+        _emit_event(
+            MemorySaveStartedEvent(
+                value="second background save",
+                metadata={},
+                source_type="unified_memory",
+                parent_event_id="manual-parent",
+            )
+        )
+
+        _emit_event(
+            MemorySaveFailedEvent(
+                value="orphan save failed",
+                metadata={},
+                error="embedding connection failed",
+                source_type="unified_memory",
+                parent_event_id="manual-parent",
+                started_event_id="missing-memory-save-start",
+            )
+        )
+    finally:
+        app._unsubscribe()
+
+    assert [entry["status"] for entry in app._log_entries] == [
+        "running",
+        "running",
+        "error",
+    ]
+    assert app._log_entries[0]["args"] == "first background save"
+    assert app._log_entries[1]["args"] == "second background save"
+    assert app._log_entries[2]["args"] == "orphan save failed"
+    assert app._log_entries[2]["error"] == "embedding connection failed"
+    assert app._log_entries[2]["started_event_id"] == "missing-memory-save-start"
+    assert app._log_expanded == {2}
+
+
+def test_memory_save_completion_without_id_does_not_update_stale_row() -> None:
+    app = _app_with_plan()
+    now = time.time()
+    app._log_entries = [
+        {
+            "tool_name": "memory_save",
+            "status": "running",
+            "args": "current background save",
+            "result": None,
+            "error": None,
+            "start_time": now,
+            "duration": None,
+            "task_idx": 1,
+        },
+        {
+            "tool_name": "memory_save",
+            "status": "success",
+            "args": "stale background save",
+            "result": "stale save completed",
+            "error": None,
+            "start_time": now - 10,
+            "duration": 1.0,
+            "task_idx": 1,
+        },
+    ]
+
+    app._subscribe()
+    try:
+        _emit_event(
+            MemorySaveCompletedEvent(
+                value="current save completed",
+                metadata={},
+                save_time_ms=2800,
+                source_type="unified_memory",
+                parent_event_id="manual-parent",
+            )
+        )
+    finally:
+        app._unsubscribe()
+
+    assert [entry["status"] for entry in app._log_entries] == [
+        "success",
+        "success",
+    ]
+    assert app._log_entries[0]["args"] == "current background save"
+    assert app._log_entries[0]["result"] == "current save completed"
+    assert app._log_entries[1]["args"] == "stale background save"
+    assert app._log_entries[1]["result"] == "stale save completed"
+
+
+def test_memory_save_failure_without_id_does_not_update_stale_row() -> None:
+    app = _app_with_plan()
+    now = time.time()
+    app._log_entries = [
+        {
+            "tool_name": "memory_save",
+            "status": "running",
+            "args": "current background save",
+            "result": None,
+            "error": None,
+            "start_time": now,
+            "duration": None,
+            "task_idx": 1,
+        },
+        {
+            "tool_name": "memory_save",
+            "status": "success",
+            "args": "stale background save",
+            "result": "stale save completed",
+            "error": None,
+            "start_time": now - 10,
+            "duration": 1.0,
+            "task_idx": 1,
+        },
+    ]
+
+    app._subscribe()
+    try:
+        _emit_event(
+            MemorySaveFailedEvent(
+                value="current save failed",
+                metadata={},
+                error="embedding connection failed",
+                source_type="unified_memory",
+                parent_event_id="manual-parent",
+            )
+        )
+    finally:
+        app._unsubscribe()
+
+    assert [entry["status"] for entry in app._log_entries] == ["error", "success"]
+    assert app._log_entries[0]["args"] == "current background save"
+    assert app._log_entries[0]["error"] == "embedding connection failed"
+    assert app._log_entries[1]["args"] == "stale background save"
+    assert app._log_entries[1]["result"] == "stale save completed"
+    assert app._log_entries[1]["error"] is None
+    assert app._log_expanded == {0}
+
+
+def test_memory_save_payloads_are_truncated_in_activity_log() -> None:
+    app = _app_with_plan()
+    long_args = "a" * (_LOG_ARGS_TEXT_LIMIT + 10)
+    long_result = "r" * (_LOG_RESULT_TEXT_LIMIT + 10)
+
+    app._subscribe()
+    try:
+        _emit_event(
+            MemorySaveStartedEvent(
+                value=long_args,
+                metadata={},
+                source_type="unified_memory",
+            )
+        )
+        _emit_event(
+            MemorySaveCompletedEvent(
+                value=long_result,
+                metadata={},
+                save_time_ms=8300,
+                source_type="unified_memory",
+            )
+        )
+    finally:
+        app._unsubscribe()
+
+    assert len(app._log_entries[0]["args"]) == _LOG_ARGS_TEXT_LIMIT
+    assert app._log_entries[0]["args"].endswith(_LOG_TRUNCATION_SUFFIX)
+    assert len(app._log_entries[0]["result"]) == _LOG_RESULT_TEXT_LIMIT
+    assert app._log_entries[0]["result"].endswith(_LOG_TRUNCATION_SUFFIX)
+
+
+def test_starting_next_tool_does_not_timeout_memory_save() -> None:
+    app = _app_with_plan()
+    app._subscribe()
+    try:
+        _emit_event(
+            MemorySaveStartedEvent(
+                value="9 memories (background)",
+                metadata={},
+                source_type="unified_memory",
+            )
+        )
+        _emit_event(
+            ToolUsageStartedEvent(
+                tool_name="read_website_content",
+                tool_args={"url": "https://example.com"},
+            )
+        )
+    finally:
+        app._unsubscribe()
+
+    assert app._log_entries[0]["tool_name"] == "memory_save"
+    assert app._log_entries[0]["status"] == "running"
+    assert app._log_entries[0]["error"] is None
+    assert app._log_entries[1]["tool_name"] == "read_website_content"
+    assert app._log_entries[1]["status"] == "running"
+
+
 def test_tool_failure_does_not_override_successful_plan_step_completion() -> None:
     app = _app_with_plan()
     app._subscribe()
@@ -480,6 +926,187 @@ async def test_crew_done_does_not_mark_unfinished_tool_successful() -> None:
     assert app._plan_step_status == {1: "failed", 2: "done", 3: "done"}
 
 
+@pytest.mark.asyncio
+async def test_crew_done_does_not_timeout_memory_save() -> None:
+    app = _app_with_plan()
+
+    async with app.run_test(size=(100, 40)) as pilot:
+        app._log_entries = [
+            {
+                "tool_name": "memory_save",
+                "status": "running",
+                "args": "9 memories (background)",
+                "result": None,
+                "error": None,
+                "start_time": time.time() - 8,
+                "duration": None,
+                "task_idx": 1,
+            },
+            {
+                "tool_name": "search",
+                "status": "running",
+                "args": '{"query": "CrewAI"}',
+                "result": None,
+                "error": None,
+                "start_time": time.time() - 2,
+                "duration": None,
+                "task_idx": 1,
+            },
+        ]
+
+        app._on_crew_done("final output")
+        await pilot.pause()
+
+    assert app._log_entries[0]["status"] == "running"
+    assert app._log_entries[0]["error"] is None
+    assert app._log_entries[1]["status"] == "timeout"
+    assert app._log_entries[1]["error"] == "No result received before crew completed"
+
+
+@pytest.mark.asyncio
+async def test_crew_done_keeps_memory_save_subscription_until_completion(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        "crewai_cli.crew_run_tui._MEMORY_SAVE_DRAIN_GRACE_SECONDS", 0.05
+    )
+    app = _app_with_plan()
+    auto_unsubscribed = False
+
+    async with app.run_test(size=(100, 40)) as pilot:
+        try:
+            assert app._event_handlers
+            started_event = MemorySaveStartedEvent(
+                value="9 memories (background)",
+                metadata={},
+                source_type="unified_memory",
+            )
+            _emit_event(started_event)
+
+            app._on_crew_done("final output")
+            await pilot.pause()
+
+            assert app._log_entries[0]["status"] == "running"
+            assert app._event_handlers
+
+            _emit_event(
+                MemorySaveCompletedEvent(
+                    value="9 memories saved",
+                    metadata={},
+                    save_time_ms=8300,
+                    source_type="unified_memory",
+                    started_event_id=started_event.event_id,
+                )
+            )
+            await pilot.pause()
+
+            assert app._event_handlers
+            await pilot.pause(0.08)
+            auto_unsubscribed = not app._event_handlers
+        finally:
+            app._unsubscribe()
+
+    assert app._log_entries[0]["tool_name"] == "memory_save"
+    assert app._log_entries[0]["status"] == "success"
+    assert app._log_entries[0]["result"] == "9 memories saved"
+    assert app._log_entries[0]["error"] is None
+    assert app._log_entries[0]["duration"] == 8.3
+    assert auto_unsubscribed is True
+
+
+@pytest.mark.asyncio
+async def test_crew_done_waits_for_queued_memory_save_events(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        "crewai_cli.crew_run_tui._MEMORY_SAVE_DRAIN_GRACE_SECONDS", 0.05
+    )
+    app = _app_with_plan()
+    auto_unsubscribed = False
+
+    async with app.run_test(size=(100, 40)) as pilot:
+        try:
+            assert app._event_handlers
+
+            app._on_crew_done("final output")
+
+            assert app._event_handlers
+            started_event = MemorySaveStartedEvent(
+                value="9 memories (background)",
+                metadata={},
+                source_type="unified_memory",
+                parent_event_id="manual-parent",
+            )
+            _emit_event(started_event)
+            await pilot.pause()
+
+            assert app._log_entries[0]["tool_name"] == "memory_save"
+            assert app._log_entries[0]["status"] == "running"
+
+            _emit_event(
+                MemorySaveCompletedEvent(
+                    value="9 memories saved",
+                    metadata={},
+                    save_time_ms=8300,
+                    source_type="unified_memory",
+                    parent_event_id="manual-parent",
+                    started_event_id=started_event.event_id,
+                )
+            )
+            await pilot.pause()
+
+            assert app._event_handlers
+            await pilot.pause(0.08)
+            auto_unsubscribed = not app._event_handlers
+        finally:
+            app._unsubscribe()
+
+    assert app._log_entries[0]["tool_name"] == "memory_save"
+    assert app._log_entries[0]["status"] == "success"
+    assert app._log_entries[0]["args"] == "9 memories (background)"
+    assert app._log_entries[0]["result"] == "9 memories saved"
+    assert app._log_entries[0]["error"] is None
+    assert app._log_entries[0]["duration"] == 8.3
+    assert auto_unsubscribed is True
+
+
+@pytest.mark.asyncio
+async def test_crew_failed_does_not_timeout_memory_save() -> None:
+    app = _app_with_plan()
+
+    async with app.run_test(size=(100, 40)) as pilot:
+        app._log_entries = [
+            {
+                "tool_name": "memory_save",
+                "status": "running",
+                "args": "9 memories (background)",
+                "result": None,
+                "error": None,
+                "start_time": time.time() - 8,
+                "duration": None,
+                "task_idx": 1,
+            },
+            {
+                "tool_name": "search",
+                "status": "running",
+                "args": '{"query": "CrewAI"}',
+                "result": None,
+                "error": None,
+                "start_time": time.time() - 2,
+                "duration": None,
+                "task_idx": 1,
+            },
+        ]
+
+        app._on_crew_failed("boom")
+        await pilot.pause()
+
+    assert app._log_entries[0]["status"] == "running"
+    assert app._log_entries[0]["error"] is None
+    assert app._log_entries[1]["status"] == "error"
+    assert app._log_entries[1]["error"] == "No result received before crew failed"
+
+
 def test_streamed_step_observation_updates_named_step_only() -> None:
     app = _app_with_plan()
 

lib/cli/tests/test_flow_commands.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from pathlib import Path
+import subprocess
+
+import click
+import pytest
+from click.testing import CliRunner
+
+from crewai_cli.cli import flow_run
+import crewai_cli.plot_flow as plot_flow_module
+
+
+FLOW_YAML = """\
+schema: crewai.flow/v1
+name: TestFlow
+config:
+  suppress_flow_events: true
+methods:
+  begin:
+    start: true
+    do:
+      call: expression
+      expr: "'AI'"
+"""
+
+
+def _write_flow_project(project_root: Path) -> None:
+    (project_root / "flow.yaml").write_text(FLOW_YAML, encoding="utf-8")
+    (project_root / "pyproject.toml").write_text(
+        '[project]\nname = "demo"\n\n'
+        '[tool.crewai]\ntype = "flow"\ndefinition = "flow.yaml"\n',
+        encoding="utf-8",
+    )
+
+
+def test_flow_kickoff_runs_configured_declarative_definition(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    _write_flow_project(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("UV_RUN_RECURSION_DEPTH", "1")
+
+    result = CliRunner().invoke(flow_run)
+
+    assert result.exit_code == 0
+    assert (
+        "The command 'crewai flow kickoff' is deprecated. Use 'crewai run' instead."
+        in result.output
+    )
+    assert "AI\n" in result.output
+    assert "Running the Flow" not in result.output
+
+
+def test_plot_flow_runs_configured_declarative_definition(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    _write_flow_project(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("UV_RUN_RECURSION_DEPTH", "1")
+
+    plot_flow_module.plot_flow()
+
+
+def test_flow_kickoff_delegates_to_run_crew(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    calls = []
+
+    monkeypatch.setattr(
+        "crewai_cli.cli.run_crew",
+        lambda **kwargs: calls.append(kwargs),
+    )
+
+    result = CliRunner().invoke(flow_run)
+
+    assert result.exit_code == 0
+    assert calls == [
+        {"trained_agents_file": None, "definition": None, "inputs": None},
+    ]
+
+
+def test_plot_flow_keeps_python_entrypoint_without_definition(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    subprocess_calls = []
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(
+        subprocess,
+        "run",
+        lambda command, **kwargs: subprocess_calls.append((command, kwargs)),
+    )
+
+    plot_flow_module.plot_flow()
+
+    assert subprocess_calls == [
+        (
+            ["uv", "run", "plot"],
+            {"capture_output": False, "text": True, "check": True},
+        )
+    ]
+
+
+def test_configured_project_declarative_flow(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(FLOW_YAML, encoding="utf-8")
+    (tmp_path / "pyproject.toml").write_text(
+        '[tool.crewai]\ntype = "flow"\ndefinition = " flow.yaml "\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    assert configured_project_declarative_flow() == definition_path.resolve()
+
+
+@pytest.mark.parametrize(
+    ("definition", "expected_error"),
+    [
+        ("C:/tmp/flow.yaml", "must be relative to the project root"),
+        ("~/flow.yaml", "must be a project-local path"),
+        ("../flow.yaml", "must resolve inside the project root"),
+    ],
+)
+def test_configured_project_declarative_flow_rejects_unsafe_paths(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    definition: str,
+    expected_error: str,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "pyproject.toml").write_text(
+        f'[tool.crewai]\ntype = "flow"\ndefinition = "{definition}"\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    with pytest.raises(click.UsageError) as exc_info:
+        configured_project_declarative_flow()
+
+    assert expected_error in exc_info.value.message
+
+
+def test_configured_project_declarative_flow_allows_normalized_project_path(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(FLOW_YAML, encoding="utf-8")
+    (tmp_path / "src").mkdir()
+    (tmp_path / "pyproject.toml").write_text(
+        '[tool.crewai]\ntype = "flow"\ndefinition = "src/../flow.yaml"\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    assert configured_project_declarative_flow() == definition_path.resolve()
+
+
+def test_configured_project_declarative_flow_rejects_absolute_path(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    definition = tmp_path / "flow.yaml"
+    (tmp_path / "pyproject.toml").write_text(
+        f'[tool.crewai]\ntype = "flow"\ndefinition = "{definition.as_posix()}"\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    with pytest.raises(click.UsageError) as exc_info:
+        configured_project_declarative_flow()
+
+    assert "must be relative to the project root" in exc_info.value.message
+
+
+def test_configured_project_declarative_flow_rejects_symlink_escape(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    outside_definition = tmp_path.parent / "outside-flow.yaml"
+    outside_definition.write_text(FLOW_YAML, encoding="utf-8")
+    link = tmp_path / "flow.yaml"
+    try:
+        link.symlink_to(outside_definition)
+    except (NotImplementedError, OSError) as exc:
+        pytest.skip(f"symlinks unavailable: {exc}")
+
+    (tmp_path / "pyproject.toml").write_text(
+        '[tool.crewai]\ntype = "flow"\ndefinition = "flow.yaml"\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    with pytest.raises(click.UsageError) as exc_info:
+        configured_project_declarative_flow()
+
+    assert "must resolve inside the project root" in exc_info.value.message
+
+
+def test_configured_project_declarative_flow_rejects_missing_file(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "pyproject.toml").write_text(
+        '[tool.crewai]\ntype = "flow"\ndefinition = "missing-flow.yaml"\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    with pytest.raises(click.UsageError) as exc_info:
+        configured_project_declarative_flow()
+
+    assert "must point to an existing file" in exc_info.value.message
+
+
+def test_configured_project_declarative_flow_rejects_directory(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "flow.yaml").mkdir()
+    (tmp_path / "pyproject.toml").write_text(
+        '[tool.crewai]\ntype = "flow"\ndefinition = "flow.yaml"\n',
+        encoding="utf-8",
+    )
+
+    from crewai_cli.run_declarative_flow import configured_project_declarative_flow
+
+    with pytest.raises(click.UsageError) as exc_info:
+        configured_project_declarative_flow()
+
+    assert "must point to a regular file" in exc_info.value.message

lib/cli/tests/test_kickoff_flow.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import sys
+
+from crewai_cli import kickoff_flow
+
+
+def test_loads_conversational_flow_from_kickoff_script(tmp_path, monkeypatch) -> None:
+    package_dir = tmp_path / "src" / "demo_chat"
+    package_dir.mkdir(parents=True)
+    (package_dir / "__init__.py").write_text("")
+    (package_dir / "main.py").write_text(
+        "\n".join(
+            [
+                "from crewai.flow import Flow",
+                "",
+                "class DemoChatFlow(Flow):",
+                "    conversational = True",
+            ]
+        )
+    )
+    (tmp_path / "pyproject.toml").write_text(
+        "\n".join(
+            [
+                "[project]",
+                'name = "demo-chat"',
+                "[project.scripts]",
+                'kickoff = "demo_chat.main:kickoff"',
+            ]
+        )
+    )
+    monkeypatch.chdir(tmp_path)
+    sys.modules.pop("demo_chat.main", None)
+    sys.modules.pop("demo_chat", None)
+
+    flow = kickoff_flow._load_conversational_flow_from_kickoff_script()
+
+    assert flow is not None
+    assert type(flow).__name__ == "DemoChatFlow"
+    assert flow.conversational is True
+
+
+def test_kickoff_flow_falls_back_to_uv_when_no_conversational_flow(
+    monkeypatch,
+) -> None:
+    calls: list[list[str]] = []
+
+    def fake_run(command, capture_output, text, check):
+        calls.append(command)
+
+        class Result:
+            stderr = ""
+
+        return Result()
+
+    monkeypatch.setattr(
+        kickoff_flow, "_load_conversational_flow_from_kickoff_script", lambda: None
+    )
+    monkeypatch.setattr(kickoff_flow.subprocess, "run", fake_run)
+
+    kickoff_flow.kickoff_flow()
+
+    assert calls == [["uv", "run", "kickoff"]]

lib/cli/tests/test_run_crew.py

@@ -5,12 +5,33 @@ from pathlib import Path
 import subprocess
 import sys
 
+import click
 import pytest
 from crewai_core.constants import CREWAI_TRAINED_AGENTS_FILE_ENV
 
 import crewai_cli.run_crew as run_crew_module
 
 
+def test_missing_crewai_package_shows_full_install_hint(monkeypatch):
+    def missing_crewai_package():
+        raise ModuleNotFoundError("No module named 'crewai'", name="crewai")
+
+    monkeypatch.setattr(
+        run_crew_module, "_import_find_crew_json_file", missing_crewai_package
+    )
+
+    with pytest.raises(click.ClickException) as exc_info:
+        run_crew_module.find_crew_json_file()
+
+    message = exc_info.value.message
+    assert "CrewAI CLI is installed without the `crewai` package" in message
+    assert (
+        "uv tool install --force --prerelease=allow 'crewai[tools]==1.14.8a1'"
+        in message
+    )
+    assert "quotes are required in zsh" in message
+
+
 def test_run_crew_forwards_trained_agents_file_to_json_crews(monkeypatch):
     """crewai run -f must reach JSON crews, not only classic subprocess crews."""
     monkeypatch.setattr(run_crew_module, "_has_json_crew", lambda: True)
@@ -547,3 +568,175 @@ def test_has_json_crew_true_without_pyproject(monkeypatch, tmp_path: Path):
     (tmp_path / "crew.jsonc").write_text("{}")
 
     assert run_crew_module._has_json_crew() is True
+
+
+def test_run_crew_rejects_inputs_without_definition():
+    with pytest.raises(click.UsageError) as exc_info:
+        run_crew_module.run_crew(inputs='{"topic":"AI"}')
+
+    assert "--inputs requires --definition" in exc_info.value.message
+
+
+def test_run_crew_rejects_filename_with_explicit_definition():
+    with pytest.raises(click.UsageError) as exc_info:
+        run_crew_module.run_crew(
+            trained_agents_file="trained.pkl",
+            definition="flow.yaml",
+        )
+
+    assert "--filename can only be used when running crews" in exc_info.value.message
+
+
+def test_run_crew_runs_explicit_declarative_definition(monkeypatch, capsys):
+    calls = []
+
+    def fake_run_declarative_flow(definition: str, inputs: str | None = None):
+        calls.append((definition, inputs))
+
+    monkeypatch.setattr(
+        "crewai_cli.run_declarative_flow.run_declarative_flow",
+        fake_run_declarative_flow,
+    )
+
+    run_crew_module.run_crew(definition="flow.yaml", inputs='{"topic":"AI"}')
+
+    captured = capsys.readouterr()
+    assert "experimental" not in captured.out.lower()
+    assert calls == [("flow.yaml", '{"topic":"AI"}')]
+
+
+def test_run_crew_runs_classic_crew_project(monkeypatch, capsys):
+    calls = []
+
+    monkeypatch.setattr(run_crew_module, "_has_json_crew", lambda: False)
+    monkeypatch.setattr(
+        run_crew_module,
+        "read_toml",
+        lambda: {"tool": {"crewai": {"type": "crew"}}},
+    )
+    monkeypatch.setattr(
+        run_crew_module,
+        "_execute_uv_script",
+        lambda script_name, **kwargs: calls.append((script_name, kwargs)),
+    )
+
+    run_crew_module.run_crew(trained_agents_file="trained.pkl")
+
+    assert capsys.readouterr().out == ""
+    assert calls == [
+        (
+            "run_crew",
+            {"entity_type": "crew", "trained_agents_file": "trained.pkl"},
+        )
+    ]
+
+
+def test_run_crew_runs_python_flow_project(monkeypatch, capsys):
+    calls = []
+
+    monkeypatch.setattr(run_crew_module, "_has_json_crew", lambda: False)
+    monkeypatch.setattr(
+        run_crew_module,
+        "read_toml",
+        lambda: {"tool": {"crewai": {"type": "flow"}}},
+    )
+    monkeypatch.setattr(
+        run_crew_module,
+        "_execute_uv_script",
+        lambda script_name, **kwargs: calls.append((script_name, kwargs)),
+    )
+    monkeypatch.setattr(
+        "crewai_cli.kickoff_flow._load_conversational_flow_from_kickoff_script",
+        lambda: None,
+    )
+
+    run_crew_module.run_crew()
+
+    assert capsys.readouterr().out == ""
+    assert calls == [("kickoff", {"entity_type": "flow"})]
+
+
+def test_run_crew_runs_conversational_flow_tui(monkeypatch, capsys):
+    class Flow:
+        pass
+
+    flow = Flow()
+    calls = []
+
+    monkeypatch.setattr(run_crew_module, "_has_json_crew", lambda: False)
+    monkeypatch.setattr(
+        run_crew_module,
+        "read_toml",
+        lambda: {"tool": {"crewai": {"type": "flow"}}},
+    )
+    monkeypatch.setattr(
+        "crewai_cli.kickoff_flow._load_conversational_flow_from_kickoff_script",
+        lambda: flow,
+    )
+    monkeypatch.setattr(
+        "crewai_cli.kickoff_flow._run_conversational_flow_tui",
+        lambda loaded_flow: calls.append(loaded_flow),
+    )
+    monkeypatch.setattr(
+        run_crew_module,
+        "_execute_uv_script",
+        lambda *_args, **_kwargs: pytest.fail(
+            "conversational flows must use the TUI"
+        ),
+    )
+
+    run_crew_module.run_crew()
+
+    assert capsys.readouterr().out == ""
+    assert calls == [flow]
+
+
+def test_run_crew_rejects_filename_for_flow_project(monkeypatch):
+    monkeypatch.setattr(run_crew_module, "_has_json_crew", lambda: False)
+    monkeypatch.setattr(
+        run_crew_module,
+        "read_toml",
+        lambda: {"tool": {"crewai": {"type": "flow"}}},
+    )
+
+    with pytest.raises(click.UsageError) as exc_info:
+        run_crew_module.run_crew(trained_agents_file="trained.pkl")
+
+    assert "--filename can only be used when running crews" in exc_info.value.message
+
+
+def test_run_crew_runs_configured_declarative_flow_project(
+    monkeypatch, tmp_path: Path, capsys
+):
+    calls = []
+
+    monkeypatch.chdir(tmp_path)
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text("schema: crewai.flow/v1\n", encoding="utf-8")
+    monkeypatch.setattr(run_crew_module, "_has_json_crew", lambda: False)
+    monkeypatch.setattr(
+        run_crew_module,
+        "read_toml",
+        lambda: {
+            "tool": {
+                "crewai": {
+                    "type": "flow",
+                    "definition": "flow.yaml",
+                }
+            }
+        },
+    )
+    monkeypatch.setattr(
+        "crewai_cli.run_declarative_flow.run_declarative_flow_in_project_env",
+        lambda definition, inputs=None: calls.append((definition, inputs)),
+    )
+    monkeypatch.setattr(
+        run_crew_module,
+        "_execute_uv_script",
+        lambda *_args, **_kwargs: pytest.fail("declarative flows must not run kickoff"),
+    )
+
+    run_crew_module.run_crew()
+
+    assert capsys.readouterr().out == ""
+    assert calls == [(definition_path.resolve(), None)]

lib/cli/tests/test_run_declarative_flow.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+import crewai_cli.run_declarative_flow as run_declarative_flow_module
+
+
+FLOW_YAML = """\
+schema: crewai.flow/v1
+name: TestFlow
+config:
+  suppress_flow_events: true
+methods:
+  begin:
+    start: true
+    do:
+      call: expression
+      expr: state.topic
+"""
+
+
+def test_run_declarative_flow_reads_definition_file(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(FLOW_YAML, encoding="utf-8")
+
+    run_declarative_flow_module.run_declarative_flow(
+        str(definition_path), '{"topic":"AI"}'
+    )
+
+    assert capsys.readouterr().out == "AI\n"
+
+
+def test_run_declarative_flow_rejects_non_object_inputs(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(FLOW_YAML, encoding="utf-8")
+
+    with pytest.raises(SystemExit):
+        run_declarative_flow_module.run_declarative_flow(
+            str(definition_path), '["not", "an", "object"]'
+        )
+
+    assert "Invalid --inputs JSON: expected an object." in capsys.readouterr().err
+
+
+def test_run_declarative_flow_reports_missing_file(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    with pytest.raises(SystemExit):
+        run_declarative_flow_module.run_declarative_flow("missing-flow.yaml")
+
+    assert (
+        "Invalid --definition path: missing-flow.yaml does not exist."
+        in capsys.readouterr().err
+    )
+
+
+def test_run_declarative_flow_reports_empty_file(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(" \n", encoding="utf-8")
+
+    with pytest.raises(SystemExit):
+        run_declarative_flow_module.run_declarative_flow(str(definition_path))
+
+    assert "Flow declaration file is empty" in capsys.readouterr().err
+
+
+@pytest.mark.parametrize(
+    "contents, expected_error",
+    [
+        ("[]\n", "Flow declaration must contain a mapping"),
+        ("schema: crewai.flow/v1\nmethods: {}\n", "Field required"),
+    ],
+)
+def test_load_declarative_flow_reports_invalid_declarations(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+    contents: str,
+    expected_error: str,
+) -> None:
+    definition_path = tmp_path / "flow.yaml"
+    definition_path.write_text(contents, encoding="utf-8")
+
+    with pytest.raises(SystemExit) as exc_info:
+        run_declarative_flow_module.load_declarative_flow(str(definition_path))
+
+    assert exc_info.value.code == 1
+    stderr = capsys.readouterr().err
+    assert f"Unable to read --definition path {definition_path}:" in stderr
+    assert expected_error in stderr
+
+
+def test_run_declarative_flow_in_project_env_uses_uv(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    subprocess_calls = []
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("UV_RUN_RECURSION_DEPTH", raising=False)
+    (tmp_path / "pyproject.toml").write_text("[project]\nname = 'demo'\n")
+    monkeypatch.setattr(
+        run_declarative_flow_module,
+        "build_env_with_all_tool_credentials",
+        lambda: {"EXISTING": "value"},
+    )
+    monkeypatch.setattr(
+        run_declarative_flow_module.subprocess,
+        "run",
+        lambda command, **kwargs: subprocess_calls.append((command, kwargs)),
+    )
+
+    run_declarative_flow_module.run_declarative_flow_in_project_env("flow.yaml")
+
+    assert subprocess_calls == [
+        (
+            ["uv", "run", "crewai", "run"],
+            {
+                "capture_output": False,
+                "text": True,
+                "check": True,
+                "env": {"EXISTING": "value"},
+            },
+        )
+    ]
+
+
+def test_run_declarative_flow_in_process_inside_uv(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("UV_RUN_RECURSION_DEPTH", "1")
+    (tmp_path / "pyproject.toml").write_text("[project]\nname = 'demo'\n")
+    (tmp_path / "flow.yaml").write_text(FLOW_YAML, encoding="utf-8")
+
+    run_declarative_flow_module.run_declarative_flow_in_project_env(
+        "flow.yaml", '{"topic":"AI"}'
+    )
+
+    assert capsys.readouterr().out == "AI\n"

lib/cli/tests/test_run_flow_definition.py

@@ -1,156 +0,0 @@
-from __future__ import annotations
-
-import json
-import sys
-import types
-
-import pytest
-import yaml
-
-from crewai_cli.run_flow_definition import run_flow_definition
-
-
-class _FakeFlow:
-    def __init__(self, definition):
-        self.definition = definition
-
-    def kickoff(self, inputs=None):
-        return {
-            "flow": self.definition["name"],
-            "inputs": inputs or {},
-        }
-
-
-class _FakeFlowFactory:
-    @classmethod
-    def from_definition(cls, definition):
-        return _FakeFlow(definition)
-
-
-class _FakeFlowDefinition:
-    @classmethod
-    def from_yaml(cls, source):
-        return yaml.safe_load(source)
-
-    @classmethod
-    def from_json(cls, source):
-        return json.loads(source)
-
-
-@pytest.fixture
-def fake_flow_runtime(monkeypatch):
-    crewai_module = types.ModuleType("crewai")
-    flow_package = types.ModuleType("crewai.flow")
-    flow_module = types.ModuleType("crewai.flow.flow")
-    flow_definition_module = types.ModuleType("crewai.flow.flow_definition")
-
-    flow_module.Flow = _FakeFlowFactory
-    flow_definition_module.FlowDefinition = _FakeFlowDefinition
-
-    monkeypatch.setitem(sys.modules, "crewai", crewai_module)
-    monkeypatch.setitem(sys.modules, "crewai.flow", flow_package)
-    monkeypatch.setitem(sys.modules, "crewai.flow.flow", flow_module)
-    monkeypatch.setitem(
-        sys.modules, "crewai.flow.flow_definition", flow_definition_module
-    )
-
-
-def _captured_json(capsys):
-    return json.loads(capsys.readouterr().out)
-
-
-def test_run_flow_definition_reads_definition_file(
-    tmp_path, capsys, fake_flow_runtime
-):
-    definition_path = tmp_path / "flow.yaml"
-    definition_path.write_text("schema: crewai.flow/v1\nname: TestFlow\n")
-
-    run_flow_definition(str(definition_path), '{"topic":"AI"}')
-
-    assert _captured_json(capsys) == {
-        "flow": "TestFlow",
-        "inputs": {"topic": "AI"},
-    }
-
-
-@pytest.mark.parametrize(
-    ("definition_source", "expected_flow_name"),
-    [
-        pytest.param(
-            "schema: crewai.flow/v1\nname: InlineFlow\n",
-            "InlineFlow",
-            id="inline-yaml",
-        ),
-        pytest.param(
-            '{"schema":"crewai.flow/v1","name":"InlineJsonFlow"}',
-            "InlineJsonFlow",
-            id="inline-json",
-        ),
-        pytest.param(
-            '{"schema":"crewai.flow/v1","name":"' + ("JsonFlow" * 500) + '"}',
-            "JsonFlow" * 500,
-            id="large-inline-json",
-        ),
-    ],
-)
-def test_run_flow_definition_accepts_inline_definitions(
-    definition_source, expected_flow_name, capsys, fake_flow_runtime
-):
-    run_flow_definition(definition_source)
-
-    assert _captured_json(capsys) == {"flow": expected_flow_name, "inputs": {}}
-
-
-@pytest.mark.parametrize(
-    ("filename", "definition_source", "expected_flow_name"),
-    [
-        pytest.param(
-            "flow.yaml",
-            "schema: crewai.flow/v1\nname: YamlFileFlow\n",
-            "YamlFileFlow",
-            id="yaml-file",
-        ),
-        pytest.param(
-            "flow.json",
-            '{"schema":"crewai.flow/v1","name":"JsonFlow"}',
-            "JsonFlow",
-            id="json-file",
-        ),
-    ],
-)
-def test_run_flow_definition_accepts_definition_files(
-    filename, definition_source, expected_flow_name, tmp_path, capsys, fake_flow_runtime
-):
-    definition_path = tmp_path / filename
-    definition_path.write_text(definition_source)
-
-    run_flow_definition(str(definition_path))
-
-    assert _captured_json(capsys) == {"flow": expected_flow_name, "inputs": {}}
-
-
-def test_run_flow_definition_rejects_non_object_inputs(fake_flow_runtime, capsys):
-    with pytest.raises(SystemExit):
-        run_flow_definition("name: TestFlow", '["not", "an", "object"]')
-
-    assert "Invalid --inputs JSON: expected an object." in capsys.readouterr().err
-
-
-def test_run_flow_definition_reports_unreadable_file(
-    monkeypatch, tmp_path, capsys, fake_flow_runtime
-):
-    definition_path = tmp_path / "flow.yaml"
-    definition_path.write_text("schema: crewai.flow/v1\nname: TestFlow\n")
-
-    def raise_permission_error(self, *args, **kwargs):
-        raise PermissionError("no access")
-
-    monkeypatch.setattr("pathlib.Path.read_text", raise_permission_error)
-
-    with pytest.raises(SystemExit):
-        run_flow_definition(str(definition_path))
-
-    err = capsys.readouterr().err
-    assert "Unable to read --definition path" in err
-    assert str(definition_path) in err
-    assert "no access" in err