Merge branch 'main' into feature/web-frontend

agent/tools/jobs_tool.py

@@ -875,20 +875,22 @@ To inspect, call this tool with `{{"operation": "scheduled inspect", "scheduled_
 HF_JOBS_TOOL_SPEC = {
     "name": "hf_jobs",
     "description": (
-        "Execute Python scripts or Docker containers on HF cloud infrastructure (CPUs/GPUs). "
+        "Execute Python scripts or Docker containers on HF cloud infrastructure (CPUs/GPUs) in one of two modes. "
+        "\n\n"
+        "**Two Modes (mutually exclusive):**\n"
+        "1. Python mode: using 'script' arg (REQUIRED) + 'dependencies'\n"
+        "2. Docker mode: using 'command' arg (REQUIRED) + 'image'\n\n"
+        "🚨 **REQUIRED:** You MUST provide exactly ONE of: 'script' (Python code as string) OR 'command' (Docker command as array). "
+        "They are mutually exclusive - provide one or the other, never both, never neither. "
+        "Do NOT call with just {'operation': 'run'} - always include your code. Example: {'operation': 'run', 'script': 'import torch; print(torch.cuda.is_available())', 'dependencies': ['torch']} or {'operation': 'run', 'command': ['duckdb', '-c', 'select 1 + 2']', 'image': 'duckdb/duckdb'}\n\n"
         "⚠️ CRITICAL for reliability: (1) Jobs run ASYNC - provide monitoring URL immediately, don't poll; "
         "(2) Set timeout >30min (default too short - training needs 2-8h); "
-        "(3) HF_TOKEN auto-loaded to secrets for Hub ops (push_to_hub, private repos);"
+        "(3) HF_TOKEN auto-loaded to secrets for Hub ops (push_to_hub, private repos); "
         "(4) Job storage EPHEMERAL - MUST push_to_hub() or ALL work is LOST. "
         "**Use when:** User wants cloud compute, training models, data processing, batch inference, GPU workloads, scheduled tasks. "
         "ALWAYS use this tool (✓), never bash 'hf jobs' commands (✗). Pass script content inline (✓), don't save to files unless requested (✗). "
         "\n\n"
         "**Operations:** run, ps, logs, inspect, cancel, scheduled run, scheduled ps, scheduled inspect, scheduled delete, scheduled suspend, scheduled resume. "
-        "\n\n"
-        "**Two Modes:**\n"
-        "1. Python mode: 'script' + 'dependencies' (UV with PEP 723 recommended for inline deps)\n"
-        "2. Docker mode: 'image' + 'command' (full environment control)\n"
-        "(script and command are mutually exclusive)\n\n"
         "**Available Hardware (vCPU/RAM/GPU):**\n"
         f"• CPU: {CPU_FLAVORS_DESC}\n"
         f"• GPU: {GPU_FLAVORS_DESC}\n"